Key-Value Storage (KVS)

Learn how to use the KVS

About

An alternative method for storing function state is through a Key-Value storage system. This approach enables storing and retrieving specific portions of the state during any interaction, eliminating the need to process the entire JSON object while reading state.

API reference

SmartWeave.kv.put(key, value) - insert a new key-value pair or update an existing key's value
SmartWeave.kv.get(key) - return the value of a given key, readable via response.data.result
SmartWeave.kv.del(key) - delete a key-value pair (it will still be accessible on-chain from the previous state reference)
SmartWeave.kv.keys(options: QueryOptions) - fetch a key based on a custom range
SmartWeave.kv.kvMap(options: QueryOptions) - Fetch a pair based on custom range

QueryOptions interface for .keys and .kvMap

interface QueryOptions {
  // Greater than or equal to (default: 0)
  gte?: number;
  // Less than (default: Object.keys(this.kv).length)
  lt?: number;
  // Reverse the order (default: false)
  reverse?: boolean;
  // Limit the result length (no default)
  limit: number;
}

Function example

After writing to the Key-Value storage (KVS), data can be retrieved by external actors/applications through the following flow:

Retrieve the value associated with the key using SmartWeave.kv.get().
The result, which is the value of the key, is then returned alongside the response transaction as a result.

function.js

export async function handle(state, action) {
  const input = action.input;

  if (input.function === "put") {
    const { key, value } = input;
    
    state.puts.push({ key, value }); // write to state
    SmartWeave.kv.put(key, value); // write to KVS
    return { state };
  }
  if (input.function === "get") {
    const { key } = input;
    
    const res = SmartWeave.kv.get(key);
    state.gets.push(res)
    return { state };
  }

  if (input.function === "del") {
    const { key } = input;
    SmartWeave.kv.del(key);
    return { state };
  }
}

state.json

{
  "puts": [],
  "gets": [],
  "publicFunctions": { "put": ["key", "value"], "get": ["key"], "del": ["key"] }
}

Contribution History

PreviousEXM API NextPastebin clone

Last updated 1 year ago

interface QueryOptions { // Greater than or equal to (default: 0) gte?: number; // Less than (default: Object.keys(this.kv).length) lt?: number; // Reverse the order (default: false) reverse?: boolean; // Limit the result length (no default) limit: number; }

export async function handle(state, action) { const input = action.input; if (input.function === "put") { const { key, value } = input; state.puts.push({ key, value }); // write to state SmartWeave.kv.put(key, value); // write to KVS return { state }; } if (input.function === "get") { const { key } = input; const res = SmartWeave.kv.get(key); state.gets.push(res) return { state }; } if (input.function === "del") { const { key } = input; SmartWeave.kv.del(key); return { state }; } }