# API

Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)

## Interfaces

| |
| --- |
| [KVContext](#interface-kvcontext) |
| [KVStoreConfig](#interface-kvstoreconfig) |
| [KVStoreEntry](#interface-kvstoreentry) |
| [KVStoreGetOptions](#interface-kvstoregetoptions) |
| [KVStoreLookupResult](#interface-kvstorelookupresult) |
| [KVStoreQuery](#interface-kvstorequery) |
| [KVStoreRemoveOptions](#interface-kvstoreremoveoptions) |
| [KVStoreSetOptions](#interface-kvstoresetoptions) |
| [KVStoreToken](#interface-kvstoretoken) |

Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)

---

### Interface: KVContext

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

See also: [WalletProtocol](./wallet.md#type-walletprotocol)

Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)

---
### Interface: KVStoreConfig

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

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

See also: [WalletInterface](./wallet.md#interface-walletinterface), [WalletProtocol](./wallet.md#type-walletprotocol)

#### Property acceptDelayedBroadcast

Whether to accept delayed broadcast

```ts
acceptDelayedBroadcast?: boolean
```

#### Property networkPreset

Network preset for overlay services

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

#### Property originator

Originator

```ts
originator?: string
```

#### Property overlayBroadcast

Whether to let overlay handle broadcasting (prevents UTXO spending on rejection)

```ts
overlayBroadcast?: boolean
```

#### Property overlayHost

The overlay service host URL

```ts
overlayHost?: string
```

#### Property protocolID

Protocol ID for the KVStore protocol

```ts
protocolID?: WalletProtocol
```
See also: [WalletProtocol](./wallet.md#type-walletprotocol)

#### Property serviceName

Service name for overlay submission

```ts
serviceName?: string
```

#### Property tokenAmount

Amount of satoshis for each token

```ts
tokenAmount?: number
```

#### Property tokenRemovalDescription

Description for token removal

```ts
tokenRemovalDescription?: string
```

#### Property tokenSetDescription

Description for token set

```ts
tokenSetDescription?: string
```

#### Property tokenUpdateDescription

Description for token update

```ts
tokenUpdateDescription?: string
```

#### Property topics

Topics for overlay submission

```ts
topics?: string[]
```

#### Property wallet

Wallet interface for operations

```ts
wallet?: WalletInterface
```
See also: [WalletInterface](./wallet.md#interface-walletinterface)

Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)

---
### Interface: KVStoreEntry

KVStore entry returned from queries

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

See also: [KVStoreToken](./kvstore.md#interface-kvstoretoken), [PubKeyHex](./wallet.md#type-pubkeyhex), [WalletProtocol](./wallet.md#type-walletprotocol)

Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)

---
### Interface: KVStoreGetOptions

Options for configuring KVStore get operations (local processing)

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

#### Property history

Whether to build and include history for each entry

```ts
history?: boolean
```

#### Property includeToken

Whether to include token transaction data in results

```ts
includeToken?: boolean
```

#### Property serviceName

Service name for overlay retrieval

```ts
serviceName?: string
```

Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)

---
### Interface: KVStoreLookupResult

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

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

Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)

---
### Interface: KVStoreQuery

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

```ts
export interface KVStoreQuery {
    key?: string;
    controller?: PubKeyHex;
    protocolID?: WalletProtocol;
    tags?: string[];
    tagQueryMode?: "all" | "any";
    limit?: number;
    skip?: number;
    sortOrder?: "asc" | "desc";
}
```

See also: [PubKeyHex](./wallet.md#type-pubkeyhex), [WalletProtocol](./wallet.md#type-walletprotocol)

#### Property tagQueryMode

Controls tag matching behavior when tags are specified.
- 'all': Requires all specified tags to be present (default)
- 'any': Requires at least one of the specified tags to be present

```ts
tagQueryMode?: "all" | "any"
```

Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)

---
### Interface: KVStoreRemoveOptions

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

See also: [WalletProtocol](./wallet.md#type-walletprotocol)

Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)

---
### Interface: KVStoreSetOptions

```ts
export interface KVStoreSetOptions {
    protocolID?: WalletProtocol;
    tokenSetDescription?: string;
    tokenUpdateDescription?: string;
    tokenAmount?: number;
    tags?: string[];
}
```

See also: [WalletProtocol](./wallet.md#type-walletprotocol)

Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)

---
### Interface: KVStoreToken

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

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

See also: [Beef](./transaction.md#class-beef)

Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)

---
## Classes

| |
| --- |
| [GlobalKVStore](#class-globalkvstore) |
| [LocalKVStore](#class-localkvstore) |

Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#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.

```ts
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](./wallet.md#interface-createactionoutput), [HexString](./wallet.md#type-hexstring), [KVStoreConfig](./kvstore.md#interface-kvstoreconfig), [KVStoreEntry](./kvstore.md#interface-kvstoreentry), [KVStoreGetOptions](./kvstore.md#interface-kvstoregetoptions), [KVStoreQuery](./kvstore.md#interface-kvstorequery), [KVStoreRemoveOptions](./kvstore.md#interface-kvstoreremoveoptions), [KVStoreSetOptions](./kvstore.md#interface-kvstoresetoptions), [OutpointString](./wallet.md#type-outpointstring)

#### Constructor

Creates an instance of the GlobalKVStore.

```ts
constructor(config: KVStoreConfig = {}) 
```
See also: [KVStoreConfig](./kvstore.md#interface-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).

```ts
async get(query: KVStoreQuery, options: KVStoreGetOptions = {}): Promise<KVStoreEntry | KVStoreEntry[] | undefined> 
```
See also: [KVStoreEntry](./kvstore.md#interface-kvstoreentry), [KVStoreGetOptions](./kvstore.md#interface-kvstoregetoptions), [KVStoreQuery](./kvstore.md#interface-kvstorequery)

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.

```ts
async remove(key: string, outputs?: CreateActionOutput[], options: KVStoreRemoveOptions = {}): Promise<HexString> 
```
See also: [CreateActionOutput](./wallet.md#interface-createactionoutput), [HexString](./wallet.md#type-hexstring), [KVStoreRemoveOptions](./kvstore.md#interface-kvstoreremoveoptions)

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.

```ts
async set(key: string, value: string, options: KVStoreSetOptions = {}): Promise<OutpointString> 
```
See also: [KVStoreSetOptions](./kvstore.md#interface-kvstoresetoptions), [OutpointString](./wallet.md#type-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](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#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.

```ts
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](./wallet.md#type-outpointstring), [WalletClient](./wallet.md#class-walletclient), [WalletInterface](./wallet.md#interface-walletinterface), [encrypt](./messages.md#variable-encrypt)

#### Constructor

Creates an instance of the localKVStore.

```ts
constructor(wallet: WalletInterface = new WalletClient(), context = "kvstore default", encrypt = true, originator?: string, acceptDelayedBroadcast = false) 
```
See also: [WalletClient](./wallet.md#class-walletclient), [WalletInterface](./wallet.md#interface-walletinterface), [encrypt](./messages.md#variable-encrypt)

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.

```ts
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.

```ts
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.

```ts
async set(key: string, value: string): Promise<OutpointString> 
```
See also: [OutpointString](./wallet.md#type-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](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)

---
## Functions

## Types

## Enums

## Variables

| |
| --- |
| [kvProtocol](#variable-kvprotocol) |
| [kvStoreInterpreter](#variable-kvstoreinterpreter) |

Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)

---

### Variable: kvProtocol

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

Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)

---
### Variable: kvStoreInterpreter

```ts
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);
        const expectedFieldCount = Object.keys(kvProtocol).length;
        const hasTagsField = decoded.fields.length === expectedFieldCount;
        const isOldFormat = decoded.fields.length === expectedFieldCount - 1;
        if (!isOldFormat && !hasTagsField)
            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](./kvstore.md#interface-kvcontext), [PushDrop](./script.md#class-pushdrop), [Transaction](./transaction.md#class-transaction), [kvProtocol](./kvstore.md#variable-kvprotocol), [toUTF8](./primitives.md#variable-toutf8)

Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)

---
