API

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interfaces

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interface: KVContext

export interface KVContext {
    key: string;
    protocolID: WalletProtocol;
}

See also: WalletProtocol

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interface: KVStoreConfig

Configuration interface for GlobalKVStore operations. Defines all options for connecting to overlay services and managing KVStore behavior.

export interface KVStoreConfig {
    overlayHost?: string;
    protocolID?: WalletProtocol;
    serviceName?: string;
    tokenAmount?: number;
    topics?: string[];
    originator?: string;
    wallet?: WalletInterface;
    networkPreset?: "mainnet" | "testnet" | "local";
    acceptDelayedBroadcast?: boolean;
    tokenSetDescription?: string;
    tokenUpdateDescription?: string;
    tokenRemovalDescription?: string;
}

See also: WalletInterface, WalletProtocol

Property acceptDelayedBroadcast

Whether to accept delayed broadcast

acceptDelayedBroadcast?: boolean

Property networkPreset

Network preset for overlay services

networkPreset?: "mainnet" | "testnet" | "local"

Property originator

Originator

originator?: string

Property overlayHost

The overlay service host URL

overlayHost?: string

Property protocolID

Protocol ID for the KVStore protocol

protocolID?: WalletProtocol

Property serviceName

Service name for overlay submission

serviceName?: string

Property tokenAmount

Amount of satoshis for each token

tokenAmount?: number

Property tokenRemovalDescription

Description for token removal

tokenRemovalDescription?: string

Property tokenSetDescription

Description for token set

tokenSetDescription?: string

Property tokenUpdateDescription

Description for token update

tokenUpdateDescription?: string

Property topics

Topics for overlay submission

topics?: string[]

Property wallet

Wallet interface for operations

wallet?: WalletInterface

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interface: KVStoreEntry

KVStore entry returned from queries

export interface KVStoreEntry {
    key: string;
    value: string;
    controller: PubKeyHex;
    protocolID: WalletProtocol;
    token?: KVStoreToken;
    history?: string[];
}

See also: KVStoreToken, PubKeyHex, WalletProtocol

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interface: KVStoreGetOptions

Options for configuring KVStore get operations (local processing)

export interface KVStoreGetOptions {
    history?: boolean;
    includeToken?: boolean;
    serviceName?: string;
}

Property history

Whether to build and include history for each entry

history?: boolean

Property includeToken

Whether to include token transaction data in results

includeToken?: boolean

Property serviceName

Service name for overlay retrieval

serviceName?: string

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interface: KVStoreLookupResult

Result structure for KVStore lookups from overlay services. Contains the transaction output information for a found key-value pair.

export interface KVStoreLookupResult {
    txid: string;
    outputIndex: number;
    outputScript: string;
    satoshis: number;
    history?: (output: any, currentDepth: number) => Promise<boolean>;
}

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interface: KVStoreQuery

Query parameters for KVStore lookups from overlay services. Used when searching for existing key-value pairs in the network.

export interface KVStoreQuery {
    key?: string;
    controller?: PubKeyHex;
    protocolID?: WalletProtocol;
    limit?: number;
    skip?: number;
    sortOrder?: "asc" | "desc";
}

See also: PubKeyHex, WalletProtocol

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interface: KVStoreRemoveOptions

export interface KVStoreRemoveOptions {
    protocolID?: WalletProtocol;
    tokenRemovalDescription?: string;
}

See also: WalletProtocol

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interface: KVStoreSetOptions

export interface KVStoreSetOptions {
    protocolID?: WalletProtocol;
    tokenSetDescription?: string;
    tokenUpdateDescription?: string;
    tokenAmount?: number;
}

See also: WalletProtocol

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interface: KVStoreToken

Token structure containing a KVStore token from overlay services. Wraps the transaction data and metadata for a key-value pair.

export interface KVStoreToken {
    txid: string;
    outputIndex: number;
    satoshis: number;
    beef: Beef;
}

See also: Beef

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Classes

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Class: GlobalKVStore

Implements a global key-value storage system which uses an overlay service to track key-value pairs. Each key-value pair is represented by a PushDrop token output. Allows getting, setting, and removing key-value pairs with optional fetching by protocolID and history tracking.

export class GlobalKVStore {
    constructor(config: KVStoreConfig = {}) 
    async get(query: KVStoreQuery, options: KVStoreGetOptions = {}): Promise<KVStoreEntry | KVStoreEntry[] | undefined> 
    async set(key: string, value: string, options: KVStoreSetOptions = {}): Promise<OutpointString> 
    async remove(key: string, outputs?: CreateActionOutput[], options: KVStoreRemoveOptions = {}): Promise<HexString> 
}

See also: CreateActionOutput, HexString, KVStoreConfig, KVStoreEntry, KVStoreGetOptions, KVStoreQuery, KVStoreRemoveOptions, KVStoreSetOptions, OutpointString

Constructor

Creates an instance of the GlobalKVStore.

constructor(config: KVStoreConfig = {}) 

Argument Details

• config
• Configuration options for the KVStore. Defaults to empty object.
• config.wallet
• Wallet to use for operations. Defaults to WalletClient.

Throws

If the configuration contains invalid parameters.

Method get

Retrieves data from the KVStore. Can query by key+controller (single result), protocolID, controller, or key (multiple results).

async get(query: KVStoreQuery, options: KVStoreGetOptions = {}): Promise<KVStoreEntry | KVStoreEntry[] | undefined> 

Returns

Single entry for key+controller queries, array for all other queries

Argument Details

• query
• Query parameters sent to overlay
• options
• Configuration options for the get operation

Method remove

Removes the key-value pair associated with the given key from the overlay service.

async remove(key: string, outputs?: CreateActionOutput[], options: KVStoreRemoveOptions = {}): Promise<HexString> 

Returns

A promise that resolves to the txid of the removal transaction if successful.

Argument Details

• key
• The key to remove.
• outputs
• Additional outputs to include in the removal transaction.
• options
• Optional parameters for the removal operation.

Throws

If the key is invalid.

If the key does not exist in the store.

If the overlay service is unreachable or the transaction fails.

If there are existing tokens that cannot be unlocked.

Method set

Sets a key-value pair. The current user (wallet identity) becomes the controller.

async set(key: string, value: string, options: KVStoreSetOptions = {}): Promise<OutpointString> 

Returns

The outpoint of the created token

Argument Details

• key
• The key to set (user computes this however they want)
• value
• The value to store
• options
• Configuration options for the set operation

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Class: LocalKVStore

Implements a key-value storage system backed by transaction outputs managed by a wallet. Each key-value pair is represented by a PushDrop token output in a specific context (basket). Allows setting, getting, and removing key-value pairs, with optional encryption.

export default class LocalKVStore {
    acceptDelayedBroadcast: boolean = false;
    constructor(wallet: WalletInterface = new WalletClient(), context = "kvstore default", encrypt = true, originator?: string, acceptDelayedBroadcast = false) 
    async get(key: string, defaultValue: string | undefined = undefined): Promise<string | undefined> 
    async set(key: string, value: string): Promise<OutpointString> 
    async remove(key: string): Promise<string[]> 
}

See also: OutpointString, WalletClient, WalletInterface, encrypt

Constructor

Creates an instance of the localKVStore.

constructor(wallet: WalletInterface = new WalletClient(), context = "kvstore default", encrypt = true, originator?: string, acceptDelayedBroadcast = false) 

Argument Details

• wallet
• The wallet interface to use. Defaults to a new WalletClient instance.
• context
• The context (basket) for namespacing keys. Defaults to 'kvstore default'.
• encrypt
• Whether to encrypt values. Defaults to true.
• originator
• — An originator to use with PushDrop and the wallet, if provided.

Throws

If the context is missing or empty.

Method get

Retrieves the value associated with a given key.

async get(key: string, defaultValue: string | undefined = undefined): Promise<string | undefined> 

Returns

A promise that resolves to the value as a string, the defaultValue if the key is not found, or undefined if no defaultValue is provided.

Argument Details

• key
• The key to retrieve the value for.
• defaultValue
• The value to return if the key is not found.

Throws

If too many outputs are found for the key (ambiguous state).

If the found output's locking script cannot be decoded or represents an invalid token format.

Method remove

Removes the key-value pair associated with the given key. It finds the existing output(s) for the key and spends them without creating a new output. If multiple outputs exist, they are all spent in the same transaction. If the key does not exist, it does nothing. If signing the removal transaction fails, it relinquishes the original outputs instead of spending.

async remove(key: string): Promise<string[]> 

Returns

A promise that resolves to the txids of the removal transactions if successful.

Argument Details

• key
• The key to remove.

Method set

Sets or updates the value associated with a given key atomically. If the key already exists (one or more outputs found), it spends the existing output(s) and creates a new one with the updated value. If multiple outputs exist for the key, they are collapsed into a single new output. If the key does not exist, it creates a new output. Handles encryption if enabled. If signing the update/collapse transaction fails, it relinquishes the original outputs and starts over with a new chain. Ensures atomicity by locking the key during the operation, preventing concurrent updates to the same key from missing earlier changes.

async set(key: string, value: string): Promise<OutpointString> 

Returns

A promise that resolves to the outpoint string (txid.vout) of the new or updated token output.

Argument Details

• key
• The key to set or update.
• value
• The value to associate with the key.

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Functions

Types

Enums

Variables

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Variable: kvProtocol

kvProtocol = {
    protocolID: 0,
    key: 1,
    value: 2,
    controller: 3,
    signature: 4
}

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Variable: kvStoreInterpreter

kvStoreInterpreter: InterpreterFunction<string, KVContext> = async (transaction: Transaction, outputIndex: number, ctx?: KVContext): Promise<string | undefined> => {
    try {
        const output = transaction.outputs[outputIndex];
        if (output == null || output.lockingScript == null)
            return undefined;
        if (ctx == null || ctx.key == null)
            return undefined;
        const decoded = PushDrop.decode(output.lockingScript);
        if (decoded.fields.length !== Object.keys(kvProtocol).length)
            return undefined;
        const key = Utils.toUTF8(decoded.fields[kvProtocol.key]);
        const protocolID = Utils.toUTF8(decoded.fields[kvProtocol.protocolID]);
        if (key !== ctx.key || protocolID !== JSON.stringify(ctx.protocolID))
            return undefined;
        try {
            return Utils.toUTF8(decoded.fields[kvProtocol.value]);
        }
        catch {
            return undefined;
        }
    }
    catch {
        return undefined;
    }
}

See also: KVContext, PushDrop, Transaction, kvProtocol, toUTF8

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables