|
1 | | -# Threefold key-value store |
2 | | -This is a key-value store which can be used by users as a database on the blockchain |
3 | | -the user can simply set,get and remove values |
| 1 | +# Threefold Key-value Store Pallet |
| 2 | + |
| 3 | +The Key-value Store Pallet is a module that enables storing key-value pairs on the blockchain, where the key is a unique identifier and the value is the data payload. |
| 4 | + |
| 5 | +Some use cases for this module are storing user profiles, preferences, or settings; storing metadata or configuration data for other modules or dapps; storing encrypted or hashed data for privacy or security purposes. The Key-value Store Pallet provides a simple and efficient way to store and access arbitrary data on the blockchain, without relying on any intermediaries or centralized servers. |
| 6 | + |
| 7 | +## Overview |
| 8 | + |
| 9 | +The Key-value Store Pallet provides [dictionary-like data storage](https://paritytech.github.io/substrate/master/frame_support/storage/trait.StorageDoubleMap.html#) and functions for: |
| 10 | +- Storing key-value pairs. |
| 11 | +- Retrieving the value associated with the specified key. |
| 12 | +- Removing a value associated with the specified key. |
| 13 | + |
| 14 | +The key value store uses under hood a map with two keys |
| 15 | + |
| 16 | +*(Key1, Key2) -> Value* |
| 17 | + |
| 18 | +**Key1** is provided by the runtime set to the account that signed the extrinsic. **Key2** and **Value** are user provided |
| 19 | + |
| 20 | +You can think of the key1 as namespace that make it easier to come up with unique names which distinguished from other accounts' names. |
| 21 | + |
| 22 | +The key value store pallet impose restrictions on the size of the keys and values. see [Assumptions](#assumptions) section. |
| 23 | + |
| 24 | +## Terminology |
| 25 | +- Key-value store: A key-value store, or key-value database is a simple database that uses an associative array (think of a map or dictionary) as the fundamental data model where each key is associated with one and only one value in a collection. This relationship is referred to as a key-value pair. |
| 26 | + |
| 27 | +## Implementations |
| 28 | +NA |
| 29 | + |
| 30 | +## Interface |
| 31 | +### Dispatchable Functions |
| 32 | +- `set(key: Vec<u8>, value: Vec<u8>)` store value for a pair of keys (key1, key2) in the store. The first key is automatically set to the account ID of the signer of the transaction, while the second key is given by the user. This way, you can assign ownership of a key to the account that created it, and also use freely any name for a key that might be already taken by someone else. If the key pair already exists in the store, the value is overwritten with the new one. Emits `EntrySet` event. |
| 33 | + |
| 34 | +- `delete(key: Vec<u8>)` remove a value stored under a pair of keys (key1, key2) from the store. The first key is automatically set to the account ID of the sender of the transaction, while the second key is given by the user. so by design, only the owner of a key pair can delete it from the store. Emits `EntryTaken` event. |
| 35 | + |
| 36 | + |
| 37 | +### Events |
| 38 | +- `EntrySet(T::AccountId, Vec<u8>, Vec<u8>)` The value for the specified key has been stored/updated. |
| 39 | +- `EntryGot(T::AccountId, Vec<u8>, Vec<u8>)` The value for the specified key has been queried. (This Event Defined But Not Used By the runtime) |
| 40 | +- `EntryTaken(T::AccountId, Vec<u8>, Vec<u8>)` The value stored under the specified key has been removed. |
| 41 | + |
| 42 | +All events included account id, the user key name and the value. |
| 43 | + |
| 44 | +### Errors |
| 45 | +- `NoValueStored` The double key (Account ID, Provided Key) is not in the `StorageDoubleMap` |
| 46 | +- `KeyIsTooLarge` The key length exceed the maximum length. see [Assumptions](#assumptions) section. |
| 47 | +- `ValueIsTooLarge` The key length exceed the maximum length. see [Assumptions](#assumptions) section. |
| 48 | + |
| 49 | +## Config |
| 50 | +```rust |
| 51 | +pub trait Config: Config { |
| 52 | + type RuntimeEvent: From<Event<Self>> + IsType<<Self as Config>::RuntimeEvent>; |
| 53 | + type WeightInfo: WeightInfo; |
| 54 | +} |
| 55 | +``` |
| 56 | + |
| 57 | +The main purpose of this trait is to act as an interface between this pallet and the runtime in which it is embedded in. A type, function, or constant in this trait is essentially left to be configured by the runtime that includes this pallet. |
| 58 | + |
| 59 | +Consequently, a runtime that wants to include this pallet must implement this trait. |
| 60 | + |
| 61 | +### Required Associated Types |
| 62 | +```rust |
| 63 | +type RuntimeEvent: From<Event<Self>> + IsType<<Self as Config>::RuntimeEvent> |
| 64 | +``` |
| 65 | + |
| 66 | +The overarching event type. |
| 67 | + |
| 68 | +```rust |
| 69 | +type WeightInfo: WeightInfo |
| 70 | +``` |
| 71 | + |
| 72 | +Weight information for extrinsics in this pallet. |
| 73 | + |
| 74 | +## Usage |
| 75 | +The following example shows how to use the key value store pallet in your runtime: |
| 76 | +```rust |
| 77 | +// Import the key value store pallet |
| 78 | +pub use pallet_kvstore; |
| 79 | + |
| 80 | +// Add it to your runtime configuration |
| 81 | +construct_runtime!( |
| 82 | + pub enum Runtime where |
| 83 | + Block = Block, |
| 84 | + NodeBlock = opaque::Block, |
| 85 | + UncheckedExtrinsic = UncheckedExtrinsic |
| 86 | + { |
| 87 | + // ... |
| 88 | + KeyValueStore: pallet_kvstore::{Pallet, Call, Storage, Event<T>}, |
| 89 | + } |
| 90 | +); |
| 91 | + |
| 92 | +// Implement the config trait for the key value store pallet |
| 93 | +impl pallet_kvstore::Config for Runtime { |
| 94 | + type RuntimeEvent = RuntimeEvent; |
| 95 | + type WeightInfo = pallet_kvstore::weights::SubstrateWeight<Runtime>; |
| 96 | +} |
| 97 | +``` |
| 98 | +## Genesis config |
| 99 | +NA |
| 100 | + |
| 101 | +## Assumptions |
| 102 | +- The key length must not exceed 512 bytes. |
| 103 | +- The value length must not exceed 2048 bytes. |
| 104 | +- The user is responsible for ensuring the uniqueness of the key within their account, otherwise the previous value associated with the key will be replaced or updated. |
| 105 | +- The stored information is publicly accessible and queryable. This means that anyone can see your data without your permission. The user must not store any sensitive information unencrypted, such as personal details, passwords, credit card numbers, or confidential information. Doing so can have serious consequences. Please use encryption tools to protect your sensitive data before storing it on this store. |
0 commit comments