Documentation / @xo-cash/state

@xo-cash/state

XO state management and storage package for the XO Engine. This package provides a unified interface for managing local state persistence and synchronization with remote state servers.

⚠️ This project is in early development phase. Use it only if you understand what you are doing and accept the risks. Do not use funds you are not willing to lose. Minor version bumps may introduce breaking changes

Overview

The state package is responsible for:

• Local State Persistence: Storing and retrieving XO templates, invitations, locking bytecodes, unspent outputs, and events
• Storage Abstraction: Providing a consistent API across different storage backends (Supported: IndexedDB and SQLite)
• State Synchronization: Managing state sync with remote servers

Installation

npm install @xo-cash/state

Basic Setup

import { createStorageAdapter, StorageType, State } from '@xo-cash/state';

// Create a storage adapter
const storage = await createStorageAdapter({
    storageType: StorageType.INDEXEDDB,
    // Identifies the account so each account's data is kept separate
    accountHash,
    databasePath: './',
    databaseFilename: 'XO',
});

// Create a state instance
const state = new State(storage);

// Use the state
const retrievedTemplate = await state.getTemplate('template-id');

Links

• Repository
• Issues

License

MIT

ArchiveFilter

Defined in: source/storages/types.ts:367

Filter used to control which records a list method returns based on archive state.

Enumeration Members

Enumeration Member	Value	Description	Defined in
Exclude	"exclude"	Return only records that are not archived.	source/storages/types.ts:370
Include	"include"	Return both archived and unarchived records.	source/storages/types.ts:373
Only	"only"	Return only archived records.	source/storages/types.ts:376

---

ArchiveStatus

Defined in: source/storages/types.ts:270

Archive status persisted on stored records. Stored as 0 or 1 so IndexedDB can index it.

Enumeration Members

Enumeration Member	Value	Defined in
Archived	1	source/storages/types.ts:272
Unarchived	0	source/storages/types.ts:271

---

DatabaseState

Defined in: source/storages/types.ts:32

The database lifecycle of a storage adapter instance.

Enumeration Members

Enumeration Member	Value	Description	Defined in
Closed	"closed"	The database is closed and all resources are released.	source/storages/types.ts:41
Ready	"ready"	The database is initialized and ready for use.	source/storages/types.ts:38
Uninitialized	"uninitialized"	The database is not initialized.	source/storages/types.ts:35

---

StorageType

Defined in: source/storages/types.ts:24

Supported storage types for local storage.

• INDEXEDDB: Works in browsers and Node.js (with shim)
• SQLITE: For Node.js and mobile applications

Enumeration Members

Enumeration Member	Value	Defined in
INDEXEDDB	"indexeddb"	source/storages/types.ts:25
SQLITE	"sqlite"	source/storages/types.ts:26

---

UnspentOutputStatus

Defined in: source/storages/types.ts:70

Status of an unspent output in the storage.

Enumeration Members

Enumeration Member	Value	Defined in
CONFIRMED	"confirmed"	source/storages/types.ts:72
PENDING	"pending"	source/storages/types.ts:71

---

ArchiveFilterInvalidError

Defined in: source/errors.ts:284

Thrown when a list request names an archive filter that is not one of the supported filters.

Extends

• Error

Constructors

Constructor

new ArchiveFilterInvalidError(archiveFilter): ArchiveFilterInvalidError;

Defined in: index.d.mts:170

Parameters

Parameter	Type
archiveFilter	string

Returns

ArchiveFilterInvalidError

Overrides

Error.constructor

Properties

Property	Modifier	Type	Description	Defined in
archiveFilter	readonly	string	Archive filter that was requested.	source/errors.ts:288

---

DatabaseClosedError

Defined in: source/errors.ts:121

Thrown when an operation is attempted on a storage instance that has already been closed.

Extends

• Error

Constructors

Constructor

new DatabaseClosedError(): DatabaseClosedError;

Defined in: source/errors.ts:121

Returns

DatabaseClosedError

Overrides

Error.constructor

---

DatabaseDataCorruptedError

Defined in: source/errors.ts:132

Thrown when stored data fails structural validation.

Extends

• Error

Constructors

Constructor

new DatabaseDataCorruptedError(reason?): DatabaseDataCorruptedError;

Defined in: index.d.mts:78

Parameters

Parameter	Type
reason?	string

Returns

DatabaseDataCorruptedError

Overrides

Error.constructor

---

DatabaseDeleteOperationFailedError

Defined in: source/errors.ts:170

Thrown when an unexpected failure occurs during a delete operation in storage.

Extends

• Error

Constructors

Constructor

new DatabaseDeleteOperationFailedError(entityName, originalError?): DatabaseDeleteOperationFailedError;

Defined in: index.d.mts:106

Parameters

Parameter	Type
entityName	string
originalError?	unknown

Returns

DatabaseDeleteOperationFailedError

Overrides

Error.constructor

Properties

Property	Modifier	Type	Description	Defined in
entityName	readonly	string	Name of the entity that was being deleted.	source/errors.ts:174
originalError	readonly	unknown	Error from the database driver, also kept as the native cause.	source/errors.ts:179

---

DatabaseDeletionBlockedError

Defined in: source/errors.ts:216

Thrown when deletion of the full database is blocked by another open connection.

Extends

• Error

Constructors

Constructor

new DatabaseDeletionBlockedError(databaseName): DatabaseDeletionBlockedError;

Defined in: index.d.mts:130

Parameters

Parameter	Type
databaseName	string

Returns

DatabaseDeletionBlockedError

Overrides

Error.constructor

Properties

Property	Modifier	Type	Description	Defined in
databaseName	readonly	string	Name of the database that was being deleted.	source/errors.ts:220

---

DatabaseDeletionFailedError

Defined in: source/errors.ts:193

Thrown when deletion of the full database fails unexpectedly.

Extends

• Error

Constructors

Constructor

new DatabaseDeletionFailedError(databaseName, originalError?): DatabaseDeletionFailedError;

Defined in: index.d.mts:120

Parameters

Parameter	Type
databaseName	string
originalError?	unknown

Returns

DatabaseDeletionFailedError

Overrides

Error.constructor

Properties

Property	Modifier	Type	Description	Defined in
databaseName	readonly	string	Name of the database that was being deleted.	source/errors.ts:197
originalError	readonly	unknown	Error from the database driver, also kept as the native cause.	source/errors.ts:202

---

DatabaseNotInitializedError

Defined in: source/errors.ts:89

Thrown when the database is used before it is initialized, or when initialization fails.

Extends

• Error

Constructors

Constructor

new DatabaseNotInitializedError(reason?): DatabaseNotInitializedError;

Defined in: index.d.mts:56

Parameters

Parameter	Type
reason?	string

Returns

DatabaseNotInitializedError

Overrides

Error.constructor

---

DatabaseWriteOperationFailedError

Defined in: source/errors.ts:147

Thrown when an unexpected failure occurs during a write operation in storage.

Extends

• Error

Constructors

Constructor

new DatabaseWriteOperationFailedError(entityName, originalError?): DatabaseWriteOperationFailedError;

Defined in: index.d.mts:92

Parameters

Parameter	Type
entityName	string
originalError?	unknown

Returns

DatabaseWriteOperationFailedError

Overrides

Error.constructor

Properties

Property	Modifier	Type	Description	Defined in
entityName	readonly	string	Name of the entity that was being written, such as template.	source/errors.ts:151
originalError	readonly	unknown	Error from the database driver, also kept as the native cause.	source/errors.ts:156

---

InvitationAlreadyExistsInStoreError

Defined in: source/errors.ts:250

Thrown when a new invitation is stored under an identifier that is already stored.

Extends

• Error

Constructors

Constructor

new InvitationAlreadyExistsInStoreError(invitationIdentifier): InvitationAlreadyExistsInStoreError;

Defined in: index.d.mts:150

Parameters

Parameter	Type
invitationIdentifier	string

Returns

InvitationAlreadyExistsInStoreError

Overrides

Error.constructor

Properties

Property	Modifier	Type	Description	Defined in
invitationIdentifier	readonly	string	Invitation identifier that is already stored.	source/errors.ts:254

---

InvitationNotFoundInStoreError

Defined in: source/errors.ts:233

Thrown when an invitation is not found in the store.

Extends

• Error

Constructors

Constructor

new InvitationNotFoundInStoreError(invitationIdentifier): InvitationNotFoundInStoreError;

Defined in: index.d.mts:140

Parameters

Parameter	Type
invitationIdentifier	string

Returns

InvitationNotFoundInStoreError

Overrides

Error.constructor

Properties

Property	Modifier	Type	Description	Defined in
invitationIdentifier	readonly	string	Invitation identifier that was looked up.	source/errors.ts:237

---

QueryFieldsLimitExceededError

Defined in: source/errors.ts:49

Thrown when more than one query field is provided to a storage method.

Extends

• Error

Constructors

Constructor

new QueryFieldsLimitExceededError(storeName, providedFields): QueryFieldsLimitExceededError;

Defined in: index.d.mts:40

Parameters

Parameter	Type
storeName	string
providedFields	string[]

Returns

QueryFieldsLimitExceededError

Overrides

Error.constructor

Properties

Property	Modifier	Type	Description	Defined in
providedFields	readonly	string[]	Query fields that were provided.	source/errors.ts:58
storeName	readonly	string	Store the query was made against.	source/errors.ts:53

---

QueryInvalidError

Defined in: source/errors.ts:72

Thrown when a query contains no recognized fields.

Extends

• Error

Constructors

Constructor

new QueryInvalidError(storeName): QueryInvalidError;

Defined in: index.d.mts:50

Parameters

Parameter	Type
storeName	string

Returns

QueryInvalidError

Overrides

Error.constructor

Properties

Property	Modifier	Type	Description	Defined in
storeName	readonly	string	Store the query was made against.	source/errors.ts:76

---

RemoteEncryptedStateManager

Defined in: source/remote-servers.ts:6

Manager for storing and fetching of state from different servers.

Note: Not implemented yet.

Constructors

Constructor

new RemoteEncryptedStateManager(stateServers): RemoteEncryptedStateManager;

Defined in: index.d.mts:220

Initializes a new RemoteEncryptedStateManager with a list of state server URIs.

Parameters

Parameter	Type	Description
stateServers	string[]	Array of server URIs as strings.

Returns

RemoteEncryptedStateManager

Methods

getStateServers()

getStateServers(): string[];

Defined in: source/remote-servers.ts:26

Returns the array of configured remote state servers URIs.

Returns

string[]

Array of server URIs.

---

ScriptHashDataNotFoundError

Defined in: source/errors.ts:301

Thrown when script hash data is absent from storage.

Extends

• Error

Constructors

Constructor

new ScriptHashDataNotFoundError(scriptHash?): ScriptHashDataNotFoundError;

Defined in: index.d.mts:180

Parameters

Parameter	Type
scriptHash?	string

Returns

ScriptHashDataNotFoundError

Overrides

Error.constructor

Properties

Property	Modifier	Type	Description	Defined in
scriptHash	readonly	string | undefined	Script hash that was looked up when provided.	source/errors.ts:305

---

SecretDataNotFoundError

Defined in: source/errors.ts:322

Thrown when a stored script hash lists a secret lookup key that has no secret in this account's secret store.

Extends

• Error

Constructors

Constructor

new SecretDataNotFoundError(secretLookupKey): SecretDataNotFoundError;

Defined in: index.d.mts:190

Parameters

Parameter	Type
secretLookupKey	string

Returns

SecretDataNotFoundError

Overrides

Error.constructor

Properties

Property	Modifier	Type	Description	Defined in
secretLookupKey	readonly	string	Lookup key that has no stored secret.	source/errors.ts:326

---

State

Defined in: source/state.ts:62

State class responsible for managing the state of the XO Engine.

• Manages the state of the templates, invitations, script hashes, unspent outputs, and events.
• Interacts with remote servers to sync the state and maintain consistency.
• Manages blockchain and invitation state and events.

Remarks

This class does not model the eventual consistency of the blockchain and invitation. It handles the data as given, and it does not manager different states of the same data.

Example

import { createStorageAdapter, StorageType, State } from '@xo-cash/state';

// Create storage
const storage = await createStorageAdapter({
  storageType: StorageType.INDEXEDDB,
  // Identifies the account so each account's data is kept separate
  accountHash,
  databasePath: './',
  databaseFilename: 'XO',
});

// Create state
const state = new State(storage);

// Use state
const retrievedTemplate = await state.getTemplate('template-identifier');

Constructors

Constructor

new State(storage): State;

Defined in: index.d.mts:955

Creates a new State instance.

Parameters

Parameter	Type	Description
storage	XOStorage	The storage adapter

Returns

State

Methods

archiveInvitation()

archiveInvitation(invitationIdentifier): Promise<void>;

Defined in: source/state.ts:140

Archives an invitation so it no longer appears in listInvitations.

Parameters

Parameter	Type	Description
invitationIdentifier	string	Identifier of the invitation to archive

Returns

Promise<void>

Promise that resolves when archiving is complete

Throws

if no invitation exists for the given identifier

archiveTemplate()

archiveTemplate(templateIdentifier): Promise<void>;

Defined in: source/state.ts:151

Archives a template so it no longer appears in listTemplates.

Parameters

Parameter	Type	Description
templateIdentifier	string	Identifier of the template to archive

Returns

Promise<void>

Promise that resolves when archiving is complete

Throws

if no template exists for the given identifier

clearInvitationUnspentOutputReservations()

clearInvitationUnspentOutputReservations(invitationIdentifier): Promise<void>;

Defined in: source/state.ts:507

Clears local UTXO reservations held by an invitation after its transaction is broadcasted. Spent inputs no longer need to stay reserved once the transaction is on the network.

NOTICE: Consider eventual consistency when clearing reservations. Broadcasting doesn't guarantee that the transaction will be confirmed and propagated to all nodes.

Parameters

Parameter	Type	Description
invitationIdentifier	string	Invitation whose reserved outputs should be released.

Returns

Promise<void>

• Resolves when eligible reserved outputs are unreserved or when there are none.

close()

close(): Promise<void>;

Defined in: source/state.ts:538

Closes the underlying storage adapter and releases all resources. After closing, this instance cannot be used again.

Returns

Promise<void>

Promise that resolves when the storage is closed

DANGEROUS_deleteDatabase()

DANGEROUS_deleteDatabase(): Promise<void>;

Defined in: source/state.ts:551

DANGEROUS: deletes the full database used by the underlying storage adapter.

Returns

Promise<void>

Promise that resolves when database deletion is complete

Throws

if database deletion fails

Throws

if another open connection blocks deletion

Warning

This permanently deletes all local state data for the account. Use this only when you fully understand the data loss impact.

deleteUnspentOutputData()

deleteUnspentOutputData(outpointTransactionHash, outpointIndex): Promise<void>;

Defined in: source/state.ts:518

Deletes unspent output data from the state.

Parameters

Parameter	Type	Description
outpointTransactionHash	string	The transaction hash of the outpoint
outpointIndex	number	The index of the outpoint

Returns

Promise<void>

Promise that resolves when the unspent output data is deleted

executeBulkUnspentOutputReservation()

executeBulkUnspentOutputReservation(parameters): Promise<void>;

Defined in: source/state.ts:479

Sets the reservation status of an unspent output for a specific invitation.

Parameters

Parameter	Type	Description
parameters	UnspentOutputReservationParameters	Outpoints, whether to reserve or release them, and the owning invitation.

Returns

Promise<void>

Promise that resolves when the output reservation status is set

Throws

if the output doesn't exist

Throws

if the output is already reserved by another invitation

generateNextDerivativeIndex()

generateNextDerivativeIndex(templateIdentifier): Promise<number>;

Defined in: source/state.ts:194

Generates the next sequential derivative index for a template, starting at 0.

Parameters

Parameter	Type	Description
templateIdentifier	string	The template identifier to generate the next index for

Returns

Promise<number>

Promise resolving to the newly generated derivative index

Throws

if an unexpected database error occurs

getInvitation()

getInvitation(invitationIdentifier): Promise<StoredInvitation | undefined>;

Defined in: source/state.ts:111

Retrieves an invitation from the state by its identifier.

Parameters

Parameter	Type	Description
invitationIdentifier	string	Identifier for the invitation

Returns

Promise<StoredInvitation | undefined>

Promise resolving to the stored invitation data, or undefined if not found

getInvitationOrThrow()

getInvitationOrThrow(invitationIdentifier): Promise<StoredInvitation>;

Defined in: source/state.ts:122

Loads a stored invitation or throws when this account does not have it.

Parameters

Parameter	Type	Description
invitationIdentifier	string	Identifier of the invitation to load.

Returns

Promise<StoredInvitation>

• Stored invitation including this account's participation fields.

Throws

• When the invitation is not stored.

getScriptHashData()

getScriptHashData(scriptHash): Promise<ScriptHashData | undefined>;

Defined in: source/state.ts:183

Retrieves script hash data from the state by its script hash.

Parameters

Parameter	Type	Description
scriptHash	string	The script hash to look up

Returns

Promise<ScriptHashData | undefined>

Promise resolving to the script hash data, or undefined if not found

getSecretData()

getSecretData(secretLookupKey): Promise<SecretData | undefined>;

Defined in: source/state.ts:308

Retrieves secret data from the state by the lookup key it is stored under.

Parameters

Parameter	Type	Description
secretLookupKey	string	The secret lookup key to look up

Returns

Promise<SecretData | undefined>

Promise that resolves to the secret data, or undefined if not found

getTemplate()

getTemplate(templateIdentifier): Promise<StoredTemplate | undefined>;

Defined in: source/state.ts:83

Retrieves a template from the state by its identifier.

Parameters

Parameter	Type	Description
templateIdentifier	string	Identifier for the template

Returns

Promise<StoredTemplate | undefined>

Promise resolving to the template data, or undefined if not found

getTemplateOrThrow()

getTemplateOrThrow(templateIdentifier): Promise<StoredTemplate>;

Defined in: source/state.ts:94

Loads a template from state and throws if it doesn't exist

Parameters

Parameter	Type	Description
templateIdentifier	string	Identifier of the template to load.

Returns

Promise<StoredTemplate>

• The stored template with this account's archive fields.

Throws

• When the template is not stored.

getUnspentOutputData()

getUnspentOutputData(outpointTransactionHash, outpointIndex): Promise<UnspentOutputData | undefined>;

Defined in: source/state.ts:205

Retrieves unspent output data from the state.

Parameters

Parameter	Type	Description
outpointTransactionHash	string	The transaction hash of the outpoint
outpointIndex	number	The index of the outpoint

Returns

Promise<UnspentOutputData | undefined>

Promise resolving to the unspent output data, or undefined if not found

getWalletSettings()

getWalletSettings(): Promise<WalletSettings>;

Defined in: source/state.ts:214

Reads the wallet settings for this account, if any have been stored.

Returns

Promise<WalletSettings>

Promise resolving to the wallet settings, or an empty object when none exist

importTemplate()

importTemplate(untrustedJsonOrObject): Promise<{
  template: XOTemplate;
  templateIdentifier: string;
}>;

Defined in: source/state.ts:247

Imports a template after sanitization and validation.

Parameters

Parameter	Type	Description
untrustedJsonOrObject	string | XOTemplate	JSON or object containing the untrusted template to import.

Returns

Promise<{ template: XOTemplate; templateIdentifier: string; }>

• The imported template and its identifier.

Throws

• If the template is invalid.

Throws

• If an unexpected database error occurs.

initialize()

initialize(): Promise<void>;

Defined in: source/state.ts:528

Initializes the underlying storage adapter. Must be called before using any other methods. This function is idempotent, initializing multiple times returns the same connection.

Returns

Promise<void>

Promise that resolves when initialization is complete

listEventsData()

listEventsData(query): Promise<EventData[]>;

Defined in: source/state.ts:450

Lists event data matching the provided query.

Parameters

Parameter	Type	Description
query	EventDataQuery	Query to apply (e.g. eventType)

Returns

Promise<EventData[]>

Promise resolving to the matching event data

Throws

if the query contains no recognized field

listInvitations()

listInvitations(options?): Promise<StoredInvitation[]>;

Defined in: source/state.ts:386

Lists invitations stored in the state. By default only unarchived invitations are returned.

Parameters

Parameter	Type	Description
options?	StorageListOptions	Optional list options

Returns

Promise<StoredInvitation[]>

Promise resolving to an array of matching stored invitations

listScriptHashData()

listScriptHashData(query): Promise<ScriptHashData[]>;

Defined in: source/state.ts:397

Lists script hash data matching the provided query.

Parameters

Parameter	Type	Description
query	ScriptHashDataQuery	Query to apply (e.g. templateIdentifier, scriptHash, or invitationIdentifier)

Returns

Promise<ScriptHashData[]>

Promise resolving to the matching script hash data

Throws

if the query contains no recognized field

listScriptHashes()

listScriptHashes(options?): Promise<ScriptHashData[]>;

Defined in: source/state.ts:409

Lists the script hashes of every stored template. By default only the script hashes of unarchived templates are returned.

Parameters

Parameter	Type	Description
options?	StorageListOptions	Optional list options.

Returns

Promise<ScriptHashData[]>

• The script hash data of every matching template.

Throws

• When the archive filter is not one of the supported filters.

listSecretData()

listSecretData(): Promise<StoredSecretData[]>;

Defined in: source/state.ts:317

Lists all secret data in the state.

Returns

Promise<StoredSecretData[]>

Promise that resolves to the list of secret data, each with its lookup key

listSecretsForScriptHash()

listSecretsForScriptHash(scriptHash): Promise<SecretData[]>;

Defined in: source/state.ts:331

Lists the secrets stored for a script hash, in the order the script hash lists them.

Stored script hash data keeps only the lookup key of each secret, so each secret is read by its lookup key.

Parameters

Parameter	Type	Description
scriptHash	string	Script hash of a stored locking script.

Returns

Promise<SecretData[]>

• The secrets for the script hash, empty when it lists none.

Throws

• When the script hash is not stored.

Throws

• When the script hash lists a lookup key that has no stored secret.

listTemplates()

listTemplates(options?): Promise<StoredTemplate[]>;

Defined in: source/state.ts:375

Lists templates stored in the state. By default only unarchived templates are returned.

Parameters

Parameter	Type	Description
options?	StorageListOptions	Optional list options

Returns

Promise<StoredTemplate[]>

Promise resolving to an array of matching templates

listUnspentOutputsData()

listUnspentOutputsData(query?, filter?): Promise<UnspentOutputData[]>;

Defined in: source/state.ts:422

Lists unspent output data matching the provided query and optional filter. When the query is omitted or has no fields set, all unspent output data is returned.

Parameters

Parameter	Type	Description
query?	UnspentOutputDataQuery	Query to apply (e.g. templateIdentifier, reservedBy, lockingBytecode, or status)
filter?	UnspentOutputDataFilter	Optional filter to apply (e.g. reserved)

Returns

Promise<UnspentOutputData[]>

Promise resolving to the matching unspent output data

Throws

if more than one query field is provided

listUnspentOutputsForScriptHash()

listUnspentOutputsForScriptHash(scriptHash): Promise<{
  templateIdentifier: string;
  unspentOutputs: UnspentOutputData[];
  unspentOutputsByOutpointKey: Map<string, UnspentOutputData>;
}>;

Defined in: source/state.ts:435

Loads the template a stored script hash belongs to and the unspent outputs stored for that script hash.

Parameters

Parameter	Type	Description
scriptHash	string	The script hash whose stored data and unspent outputs are loaded.

Returns

Promise<{ templateIdentifier: string; unspentOutputs: UnspentOutputData[]; unspentOutputsByOutpointKey: Map<string, UnspentOutputData>; }>

• The template identifier, the stored unspent outputs, and the same outputs keyed by outpoint.

Throws

If the script hash is not found in the state.

reserveOwnUnspentOutputsForInvitation()

reserveOwnUnspentOutputsForInvitation(invitationIdentifier, inputs): Promise<void>;

Defined in: source/state.ts:493

For each invitation input outpoint, reserves the UTXO in local storage when it exists and is unreserved. Outpoints not in storage are skipped so commits may still reference external inputs.

Parameters

Parameter	Type	Description
invitationIdentifier	string	Invitation that will own the reservation.
inputs	XOInvitationInput[]	Invitation inputs that may include outpoints to reserve.

Returns

Promise<void>

• Resolves when eligible local outpoints are reserved, or when there is nothing to reserve.

Throws

• If a local outpoint is already reserved by another invitation.

Throws

• If a local outpoint is already reserved by this invitation.

storeEvent()

storeEvent(
   eventId, 
   eventType, 
   data, 
   timestamp?): Promise<void>;

Defined in: source/state.ts:364

Stores an event in the state.

Parameters

Parameter	Type	Description
eventId	string	Identifier for the event
eventType	string	Type of the event
data	unknown	Event data
timestamp?	number	Optional timestamp

Returns

Promise<void>

Promise that resolves when the event is stored

storeNewInvitation()

storeNewInvitation(invitationIdentifier, invitation): Promise<void>;

Defined in: source/state.ts:269

Stores an invitation in the state.

Parameters

Parameter	Type	Description
invitationIdentifier	string	Identifier for the invitation
invitation	StoredInvitation	The invitation data to store

Returns

Promise<void>

Promise that resolves when the invitation is stored

storeScriptHashData()

storeScriptHashData(data): Promise<void>;

Defined in: source/state.ts:298

Stores script hash data in the state.

Parameters

Parameter	Type	Description
data	ScriptHashData	The script hash data to store

Returns

Promise<void>

Promise that resolves when the script hash data is stored

storeSecretData()

storeSecretData(data): Promise<string>;

Defined in: source/state.ts:341

Stores secret data in the state.

Parameters

Parameter	Type	Description
data	SecretData	The secret data to store

Returns

Promise<string>

Promise that resolves to the secret lookup key

storeUnspentOutputData()

storeUnspentOutputData(data): Promise<void>;

Defined in: source/state.ts:351

Stores unspent output data in the state.

Parameters

Parameter	Type	Description
data	UnspentOutputData	The unspent output data to store

Returns

Promise<void>

Promise that resolves when the unspent output data is stored

unarchiveInvitation()

unarchiveInvitation(invitationIdentifier): Promise<void>;

Defined in: source/state.ts:162

Restores an archived invitation so it appears again in listInvitations.

Parameters

Parameter	Type	Description
invitationIdentifier	string	Identifier of the invitation to restore

Returns

Promise<void>

Promise that resolves when the invitation is restored

Throws

if no invitation exists for the given identifier

unarchiveTemplate()

unarchiveTemplate(templateIdentifier): Promise<void>;

Defined in: source/state.ts:173

Restores an archived template so it appears again in listTemplates.

Parameters

Parameter	Type	Description
templateIdentifier	string	Identifier of the template to restore

Returns

Promise<void>

Promise that resolves when the template is restored

Throws

if no template exists for the given identifier

unsetWalletSettings()

unsetWalletSettings(keys): Promise<void>;

Defined in: source/state.ts:235

Removes the specified fields from the stored wallet settings. Fields not listed are preserved.

Parameters

Parameter	Type	Description
keys	WalletSettingsKey[]	The field names to remove from the stored settings

Returns

Promise<void>

Promise that resolves when the fields have been removed

updateInvitation()

updateInvitation(
   invitationIdentifier, 
   invitation, 
   addedSecretsByCommitIdentifier?): Promise<void>;

Defined in: source/state.ts:284

Updates an existing invitation in the state, replacing its full contents. Should be called when an invitation evolves, for example when a new commit is appended.

Parameters

Parameter	Type	Description
invitationIdentifier	string	Identifier for the invitation
invitation	XOInvitation	The updated shared invitation. The account fields already stored with it are kept.
addedSecretsByCommitIdentifier?	Record<string, StoredCommitSecret[]>	Secrets introduced with commits this update adds, merged into the stored ones.

Returns

Promise<void>

Promise that resolves when the invitation is updated

Throws

if no invitation exists for the given identifier

updateUnspentOutputDataStatus()

updateUnspentOutputDataStatus(
   outpointTransactionHash, 
   outpointIndex, 
   status): Promise<void>;

Defined in: source/state.ts:463

Updates the status of existing unspent output data in the state.

Parameters

Parameter	Type	Description
outpointTransactionHash	string	The transaction hash of the outpoint
outpointIndex	number	The index of the outpoint
status	UnspentOutputStatus	The new status to set ('confirmed' or 'pending')

Returns

Promise<void>

Promise that resolves when the status is updated

Throws

if the output doesn't exist

updateWalletSettings()

updateWalletSettings(settings): Promise<void>;

Defined in: source/state.ts:224

Updates wallet settings for this account. Merges the provided fields into any existing settings so omitted fields are preserved.

Parameters

Parameter	Type	Description
settings	WalletSettings	Partial wallet settings to merge into storage

Returns

Promise<void>

Promise that resolves when storage is updated

---

StorageTypeUnsupportedError

Defined in: source/errors.ts:104

Thrown when a storage type that has no storage implementation is requested.

Extends

• Error

Constructors

Constructor

new StorageTypeUnsupportedError(storageType): StorageTypeUnsupportedError;

Defined in: index.d.mts:66

Parameters

Parameter	Type
storageType	string

Returns

StorageTypeUnsupportedError

Overrides

Error.constructor

Properties

Property	Modifier	Type	Description	Defined in
storageType	readonly	string	Storage type that was requested.	source/errors.ts:108

---

TemplateNotFoundInStoreError

Defined in: source/errors.ts:267

Thrown when a template is not found in the store.

Extends

• Error

Constructors

Constructor

new TemplateNotFoundInStoreError(templateIdentifier): TemplateNotFoundInStoreError;

Defined in: index.d.mts:160

Parameters

Parameter	Type
templateIdentifier	string

Returns

TemplateNotFoundInStoreError

Overrides

Error.constructor

Properties

Property	Modifier	Type	Description	Defined in
templateIdentifier	readonly	string	Template identifier that was looked up.	source/errors.ts:271

---

UnspentOutputNotFoundInStoreError

Defined in: source/errors.ts:9

Thrown when an unspent output is not found in the store.

Extends

• Error

Constructors

Constructor

new UnspentOutputNotFoundInStoreError(outpointKey): UnspentOutputNotFoundInStoreError;

Defined in: index.d.mts:12

Parameters

Parameter	Type
outpointKey	string

Returns

UnspentOutputNotFoundInStoreError

Overrides

Error.constructor

Properties

Property	Modifier	Type	Description	Defined in
outpointKey	readonly	string	Outpoint that was looked up.	source/errors.ts:13

---

UnspentOutputReservationExternalConflictError

Defined in: source/errors.ts:26

Thrown when a reservation request fails because another invitation already holds the output.

Extends

• Error

Constructors

Constructor

new UnspentOutputReservationExternalConflictError(outpointKey, reservedBy): UnspentOutputReservationExternalConflictError;

Defined in: index.d.mts:26

Parameters

Parameter	Type
outpointKey	string
reservedBy	string

Returns

UnspentOutputReservationExternalConflictError

Overrides

Error.constructor

Properties

Property	Modifier	Type	Description	Defined in
outpointKey	readonly	string	Outpoint that could not be reserved.	source/errors.ts:30
reservedBy	readonly	string	Invitation that already holds the reservation.	source/errors.ts:35

---

UnspentOutputReservationInternalConflictError

Defined in: source/errors.ts:341

Thrown when a reservation request fails because the invitation making the request already holds the output.

Extends

• Error

Constructors

Constructor

new UnspentOutputReservationInternalConflictError(outpointKey, invitationIdentifier): UnspentOutputReservationInternalConflictError;

Defined in: index.d.mts:204

Parameters

Parameter	Type
outpointKey	string
invitationIdentifier	string

Returns

UnspentOutputReservationInternalConflictError

Overrides

Error.constructor

Properties

Property	Modifier	Type	Description	Defined in
invitationIdentifier	readonly	string	Invitation that made the request and already holds the reservation.	source/errors.ts:350
outpointKey	readonly	string	Outpoint that could not be reserved.	source/errors.ts:345

---

StorageConfig

Defined in: source/storages/types.ts:52

Storage configuration options.

Properties

Property	Type	Description	Defined in
accountHash	string	SHA-256 hex hash identifying the account. Appended to the database filename to isolate each account's data.	source/storages/types.ts:58
databaseFilename?	string	Base name for the database file. The accountHash is appended to this name. Defaults to "XO".	source/storages/types.ts:64
databasePath?	string	Directory path where the database will be stored	source/storages/types.ts:61
storageType	StorageType	Type of storage to use	source/storages/types.ts:55

---

XOStorage

Defined in: source/storages/types.ts:525

Abstract storage adapter interface.

This interface hides ALL implementation details of the underlying database. All storage implementations (IndexedDB, SQLite, PostgreSQL, etc.) must implement this interface. The implementation details are completely hidden from consumers.

Example

// Create a storage adapter
const storage = await createStorageAdapter({
  storageType: StorageType.INDEXEDDB,
  // Identifies the account so each account's data is kept separate
  accountHash,
  databasePath: './',
  databaseFilename: 'XO',
});

// Use the adapter
const retrievedTemplate = await storage.getTemplate('template-identifier');

Methods

archiveInvitation()

archiveInvitation(invitationIdentifier): Promise<void>;

Defined in: source/storages/types.ts:555

Archives an invitation, the archived invitations are still accessible but they are need to be specially fetched using the archive flag.

UTXO reservations held by this invitation are unreserved before archiving.

Parameters

Parameter	Type	Description
invitationIdentifier	string	Identifier of the invitation to archive

Returns

Promise<void>

Promise that resolves when archiving is complete

Throws

if no invitation exists for the given identifier

Throws

if an unexpected database error occurs

archiveTemplate()

archiveTemplate(templateIdentifier): Promise<void>;

Defined in: source/storages/types.ts:566

Archives a template, the archived templates are still accessible but they are need to be specially fetched using the archive flag.

Parameters

Parameter	Type	Description
templateIdentifier	string	Identifier of the template to archive

Returns

Promise<void>

Promise that resolves when archiving is complete

Throws

if no template exists for the given identifier

Throws

if an unexpected database error occurs

clearInvitationUnspentOutputReservations()

clearInvitationUnspentOutputReservations(invitationIdentifier): Promise<void>;

Defined in: source/storages/types.ts:837

Clears local UTXO reservations held by an invitation after its transaction is broadcasted. Spent inputs no longer need to stay reserved once the transaction is on the network.

NOTICE: Consider eventual consistency when clearing reservations. Broadcasting doesn't guarantee that the transaction will be confirmed and propagated to all nodes.

Parameters

Parameter	Type	Description
invitationIdentifier	string	Invitation whose reserved outputs should be released.

Returns

Promise<void>

• Resolves when eligible reserved outputs are unreserved or when there are none.

close()

close(): Promise<void>;

Defined in: source/storages/types.ts:890

Closes the storage adapter and releases all resources. After closing, this instance cannot be used again. Create a new instance to reopen the database.

Returns

Promise<void>

Promise that resolves when the storage is closed

DANGEROUS_deleteDatabase()

DANGEROUS_deleteDatabase(): Promise<void>;

Defined in: source/storages/types.ts:901

DANGEROUS: Deletes the full database used by this storage adapter.

Returns

Promise<void>

Promise that resolves when database deletion is complete

Throws

If database deletion fails

Throws

If another open connection blocks deletion

Warning

This permanently deletes all local state data for the account. Use this only when you fully understand the data loss impact.

deleteUnspentOutputData()

deleteUnspentOutputData(outpointTransactionHash, outpointIndex): Promise<void>;

Defined in: source/storages/types.ts:873

Deletes unspent output data from storage.

Parameters

Parameter	Type	Description
outpointTransactionHash	string	The transaction hash of the outpoint
outpointIndex	number	The index of the outpoint

Returns

Promise<void>

Promise that resolves when the unspent output data is deleted

executeBulkUnspentOutputReservation()

executeBulkUnspentOutputReservation(parameters): Promise<void>;

Defined in: source/storages/types.ts:814

Sets the reservation status of an unspent output for a specific invitation.

Parameters

Parameter	Type	Description
parameters	UnspentOutputReservationParameters	Outpoints, whether to reserve or release them, and the owning invitation.

Returns

Promise<void>

Promise that resolves when the output reservation status is set

Throws

if the output doesn't exist

Throws

if the output is already reserved by another invitation

generateNextDerivativeIndex()

generateNextDerivativeIndex(templateIdentifier): Promise<number>;

Defined in: source/storages/types.ts:603

Generates the next sequential derivative index for a template, starting at 0.

Parameters

Parameter	Type	Description
templateIdentifier	string	The template identifier to generate the next index for

Returns

Promise<number>

Promise that resolves to the newly generated derivative index

Throws

if an unexpected database error occurs

getInvitation()

getInvitation(invitationIdentifier): Promise<StoredInvitation | undefined>;

Defined in: source/storages/types.ts:542

Retrieves an invitation from storage by its identifier.

Parameters

Parameter	Type	Description
invitationIdentifier	string	Identifier for the invitation

Returns

Promise<StoredInvitation | undefined>

Promise that resolves to the invitation data, or undefined if not found

getScriptHashData()

getScriptHashData(scriptHash): Promise<ScriptHashData | undefined>;

Defined in: source/storages/types.ts:594

Retrieves script hash data from storage by its script hash.

Parameters

Parameter	Type	Description
scriptHash	string	The script hash to look up

Returns

Promise<ScriptHashData | undefined>

Promise that resolves to the script hash data, or undefined if not found

getSecretData()

getSecretData(secretLookupKey): Promise<SecretData | undefined>;

Defined in: source/storages/types.ts:673

Retrieves secret data from storage by the lookup key it is stored under.

Parameters

Parameter	Type	Description
secretLookupKey	string	The secret lookup key to look up

Returns

Promise<SecretData | undefined>

Promise that resolves to the secret data, or undefined if not found

getTemplate()

getTemplate(templateIdentifier): Promise<StoredTemplate | undefined>;

Defined in: source/storages/types.ts:534

Retrieves a template from storage by its identifier.

Parameters

Parameter	Type	Description
templateIdentifier	string	Identifier for the template

Returns

Promise<StoredTemplate | undefined>

Promise that resolves to the template data, or undefined if not found

getUnspentOutputData()

getUnspentOutputData(outpointTransactionHash, outpointIndex): Promise<UnspentOutputData | undefined>;

Defined in: source/storages/types.ts:612

Retrieves unspent output data from storage.

Parameters

Parameter	Type	Description
outpointTransactionHash	string	The transaction hash of the outpoint
outpointIndex	number	The index of the outpoint

Returns

Promise<UnspentOutputData | undefined>

Promise that resolves to the unspent output data, or undefined if not found

getWalletSettings()

getWalletSettings(): Promise<WalletSettings>;

Defined in: source/storages/types.ts:844

Reads the wallet settings for this account, if any have been stored.

Returns

Promise<WalletSettings>

Promise that resolves to the wallet settings, or an empty object when none exist

initialize()

initialize(): Promise<void>;

Defined in: source/storages/types.ts:882

Initializes the storage adapter. Must be called before using any other methods.

Returns

Promise<void>

Promise that resolves when initialization is complete

listEvents()

listEvents(query): Promise<EventData[]>;

Defined in: source/storages/types.ts:788

Lists event data matching the provided query.

Parameters

Parameter	Type	Description
query	EventDataQuery	Query to apply (e.g. eventType)

Returns

Promise<EventData[]>

Promise that resolves to an array of events matching the query

Throws

if more than one query field is provided

Throws

if the query contains no recognized field

listInvitations()

listInvitations(options?): Promise<StoredInvitation[]>;

Defined in: source/storages/types.ts:731

Lists invitations stored in the storage. By default only unarchived invitations are returned.

Parameters

Parameter	Type	Description
options?	StorageListOptions	Optional list options

Returns

Promise<StoredInvitation[]>

Promise that resolves to an array of matching stored invitations

listScriptHashData()

listScriptHashData(query): Promise<ScriptHashData[]>;

Defined in: source/storages/types.ts:741

Lists script hash data matching the provided query.

Parameters

Parameter	Type	Description
query	ScriptHashDataQuery	Query to apply (e.g. templateIdentifier, scriptHash, or invitationIdentifier)

Returns

Promise<ScriptHashData[]>

Promise that resolves to an array of script hash data matching the query

Throws

if more than one query field is provided

Throws

if the query contains no recognized field

listScriptHashes()

listScriptHashes(options?): Promise<ScriptHashData[]>;

Defined in: source/storages/types.ts:751

Lists the script hashes of every stored template. By default only the script hashes of unarchived templates are returned.

Parameters

Parameter	Type	Description
options?	StorageListOptions	Optional list options.

Returns

Promise<ScriptHashData[]>

• The script hash data of every matching template.

Throws

• When the archive filter is not one of the supported filters.

listSecretData()

listSecretData(): Promise<StoredSecretData[]>;

Defined in: source/storages/types.ts:680

Lists all secret data in storage.

Returns

Promise<StoredSecretData[]>

Promise that resolves to the list of secret data, each with its lookup key

listSecretsForScriptHash()

listSecretsForScriptHash(scriptHash): Promise<SecretData[]>;

Defined in: source/storages/types.ts:692

Lists the secrets stored for a script hash.

Stored script hash data keeps only the lookup key of each secret, so each secret is read by its lookup key.

Parameters

Parameter	Type	Description
scriptHash	string	Script hash of a stored locking script.

Returns

Promise<SecretData[]>

• The secrets for the script hash, empty when it lists none.

Throws

• When the script hash is not stored.

Throws

• When the script hash lists a lookup key that has no stored secret.

listTemplates()

listTemplates(options?): Promise<StoredTemplate[]>;

Defined in: source/storages/types.ts:721

Lists templates stored in the storage. By default only unarchived templates are returned.

Parameters

Parameter	Type	Description
options?	StorageListOptions	Optional list options

Returns

Promise<StoredTemplate[]>

Promise that resolves to an array of matching templates

listUnspentOutputs()

listUnspentOutputs(query?, filter?): Promise<UnspentOutputData[]>;

Defined in: source/storages/types.ts:763

Lists unspent output data matching the provided query and optional filter.

When the query is omitted or has no fields set, all unspent output data is returned.

Parameters

Parameter	Type	Description
query?	UnspentOutputDataQuery	Query to apply (e.g. templateIdentifier, reservedBy, lockingBytecode, or status)
filter?	UnspentOutputDataFilter	Optional filter to apply (e.g. reserved)

Returns

Promise<UnspentOutputData[]>

Promise that resolves to an array of unspent output data matching the query and filter

Throws

if more than one query field is provided

listUnspentOutputsForScriptHash()

listUnspentOutputsForScriptHash(scriptHash): Promise<{
  templateIdentifier: string;
  unspentOutputs: UnspentOutputData[];
  unspentOutputsByOutpointKey: Map<string, UnspentOutputData>;
}>;

Defined in: source/storages/types.ts:774

Loads the template a stored script hash belongs to and the unspent outputs stored for that script hash.

Parameters

Parameter	Type	Description
scriptHash	string	The script hash whose stored data and unspent outputs are loaded.

Returns

Promise<{ templateIdentifier: string; unspentOutputs: UnspentOutputData[]; unspentOutputsByOutpointKey: Map<string, UnspentOutputData>; }>

• The template identifier, the stored unspent outputs, and the same outputs keyed by outpoint.

Throws

If the script hash is not found in the state.

reserveOwnUnspentOutputsForInvitation()

reserveOwnUnspentOutputsForInvitation(invitationIdentifier, inputs): Promise<void>;

Defined in: source/storages/types.ts:825

For each invitation input, reserves the UTXO in local storage when it exists and is unreserved.

Parameters

Parameter	Type	Description
invitationIdentifier	string	Invitation that will own the reservation.
inputs	XOInvitationInput[]	Invitation inputs that may include outpoints to reserve.

Returns

Promise<void>

• Resolves when eligible local outpoints are reserved, or when there is nothing to reserve.

Throws

• If a local outpoint is already reserved by another invitation.

Throws

• If a local outpoint is already reserved by this invitation.

storeEvent()

storeEvent(
   eventId, 
   eventType, 
   data, 
   timestamp?): Promise<void>;

Defined in: source/storages/types.ts:711

Stores an event in storage.

Parameters

Parameter	Type	Description
eventId	string	Identifier for the event
eventType	string	Type of the event
data	unknown	Event data
timestamp?	number	Optional timestamp (defaults to current time)

Returns

Promise<void>

Promise that resolves when the event is stored

storeNewInvitation()

storeNewInvitation(invitationIdentifier, invitation): Promise<void>;

Defined in: source/storages/types.ts:630

Stores an invitation in storage.

Parameters

Parameter	Type	Description
invitationIdentifier	string	Identifier for the invitation
invitation	StoredInvitation	The invitation data to store

Returns

Promise<void>

Promise that resolves when the invitation is stored

storeScriptHashData()

storeScriptHashData(data): Promise<void>;

Defined in: source/storages/types.ts:657

Stores script hash data in storage.

Parameters

Parameter	Type	Description
data	ScriptHashData	The script hash data to store

Returns

Promise<void>

Promise that resolves when the data is stored

storeSecretData()

storeSecretData(data): Promise<string>;

Defined in: source/storages/types.ts:700

Stores secret data in storage.

Parameters

Parameter	Type	Description
data	SecretData	The secret data to store

Returns

Promise<string>

Promise that resolves to the secret lookup key

storeTemplate()

storeTemplate(template): Promise<void>;

Defined in: source/storages/types.ts:621

Stores a template in storage.

Parameters

Parameter	Type	Description
template	XOTemplate	The template data to store

Returns

Promise<void>

Promise that resolves when the template is stored

storeUnspentOutputData()

storeUnspentOutputData(data): Promise<void>;

Defined in: source/storages/types.ts:665

Stores unspent output data in storage.

Parameters

Parameter	Type	Description
data	UnspentOutputData	The unspent output data to store

Returns

Promise<void>

Promise that resolves when the unspent output data is stored

unarchiveInvitation()

unarchiveInvitation(invitationIdentifier): Promise<void>;

Defined in: source/storages/types.ts:576

Restores an archived invitation.

Parameters

Parameter	Type	Description
invitationIdentifier	string	Identifier of the invitation to restore

Returns

Promise<void>

Promise that resolves when the invitation is restored

Throws

if no invitation exists for the given identifier

Throws

if an unexpected database error occurs

unarchiveTemplate()

unarchiveTemplate(templateIdentifier): Promise<void>;

Defined in: source/storages/types.ts:586

Restores an archived template.

Parameters

Parameter	Type	Description
templateIdentifier	string	Identifier of the template to restore

Returns

Promise<void>

Promise that resolves when the template is restored

Throws

if no template exists for the given identifier

Throws

if an unexpected database error occurs

unsetWalletSettings()

unsetWalletSettings(keys): Promise<void>;

Defined in: source/storages/types.ts:863

Removes the specified fields from the stored wallet settings. Fields not listed are preserved. If all fields are removed, the record becomes empty and getWalletSettings will return an empty object.

Parameters

Parameter	Type	Description
keys	WalletSettingsKey[]	The field names to remove from the stored settings

Returns

Promise<void>

Promise that resolves when the fields have been removed

updateInvitation()

updateInvitation(
   invitationIdentifier, 
   invitation, 
   addedSecretsByCommitIdentifier?): Promise<void>;

Defined in: source/storages/types.ts:645

Updates an existing invitation in storage, replacing its full contents. Should be called when an invitation evolves, for example when a new commit is appended.

The account fields already stored with the invitation are kept.

Parameters

Parameter	Type	Description
invitationIdentifier	string	Identifier for the invitation
invitation	XOInvitation	The updated shared invitation
addedSecretsByCommitIdentifier?	Record<string, StoredCommitSecret[]>	Secrets introduced with commits this update adds, merged into the stored ones

Returns

Promise<void>

Promise that resolves when the invitation is updated

Throws

if no invitation exists for the given identifier

Throws

if an unexpected database error occurs

updateUnspentOutputDataStatus()

updateUnspentOutputDataStatus(
   outpointTransactionHash, 
   outpointIndex, 
   status): Promise<void>;

Defined in: source/storages/types.ts:800

Updates the status of existing unspent output data in storage.

Parameters

Parameter	Type	Description
outpointTransactionHash	string	The transaction hash of the outpoint
outpointIndex	number	The index of the outpoint
status	UnspentOutputStatus	The new status to set ('confirmed' or 'pending')

Returns

Promise<void>

Promise that resolves when the status is updated

Throws

if the output doesn't exist

updateWalletSettings()

updateWalletSettings(settings): Promise<void>;

Defined in: source/storages/types.ts:853

Updates wallet settings for this account. Merges the provided fields into any existing settings so omitted fields are preserved.

Parameters

Parameter	Type	Description
settings	WalletSettings	Partial wallet settings to merge into storage

Returns

Promise<void>

Promise that resolves when storage is updated

Throws

if an unexpected database error occurs

---

EventData

type EventData = object;

Defined in: source/storages/types.ts:250

Event data structure returned by list operations.

---

EventDataQuery

type EventDataQuery = object;

Defined in: source/storages/types.ts:260

Query options for event data.

Properties

eventType?

optional eventType?: string;

Defined in: source/storages/types.ts:263

Query by event type

---

Outpoint

type Outpoint = object;

Defined in: source/storages/types.ts:78

Transaction outpoint used when reserving or releasing unspent outputs.

Properties

outpointTransactionHash

outpointTransactionHash: XOInvitationTransactionHash;

Defined in: source/storages/types.ts:81

The transaction hash of the outpoint

---

ScriptHashData

type ScriptHashData = object;

Defined in: source/storages/types.ts:143

Data structure for storing script hash information in the storage.

Properties

addedAtTimestampMs?

optional addedAtTimestampMs?: number;

Defined in: source/storages/types.ts:182

Unix timestamp in milliseconds when this script hash was added to storage.

scriptHash

scriptHash: string;

Defined in: source/storages/types.ts:146

The script hash of the locking bytecode

secrets?

optional secrets?: string[];

Defined in: source/storages/types.ts:172

Array of secret identifier

variables?

optional variables?: Record<string, string>;

Defined in: source/storages/types.ts:177

Variables associated with a lockingbytecode generated by an action in a template

---

ScriptHashDataQuery

type ScriptHashDataQuery = object;

Defined in: source/storages/types.ts:188

Query options for script hash data.

Properties

templateIdentifier?

optional templateIdentifier?: XOTemplateIdentifier;

Defined in: source/storages/types.ts:191

Query by template identifier

---

SecretData

type SecretData = object;

Defined in: source/storages/types.ts:105

Data structure for storing a secret in the storage.

Properties

createdAtTimestampMs?

optional createdAtTimestampMs?: number;

Defined in: source/storages/types.ts:128

Unix timestamp in milliseconds when this secret was added to storage.

secretIdentifier

secretIdentifier: XOTemplateSecretIdentifier;

Defined in: source/storages/types.ts:108

The identifier of the secret

templateIdentifier

templateIdentifier: XOTemplateIdentifier;

Defined in: source/storages/types.ts:114

Template the secret was generated under. A private key is derived under this template, so the same stored value gives a different key under any other template.

---

StorageListOptions

type StorageListOptions = object;

Defined in: source/storages/types.ts:382

Options accepted by list methods that support returning archived records.

Properties

archived?

optional archived?: ArchiveFilter;

Defined in: source/storages/types.ts:387

Filter used to control which records are returned based on archive state.

---

StoredArchiveFields

type StoredArchiveFields = object;

Defined in: source/storages/types.ts:278

Archive fields

Properties

archivedAtTimestampMs?

optional archivedAtTimestampMs?: number;

Defined in: source/storages/types.ts:283

Unix timestamp in milliseconds when this record was archived.

isArchived?

optional isArchived?: ArchiveStatus;

Defined in: source/storages/types.ts:289

Archive flag used for IndexedDB indexing. Stored as 0 or 1 because booleans are not valid IndexedDB keys to create indexes.

---

StoredCommitSecret

type StoredCommitSecret = object;

Defined in: source/storages/types.ts:295

A secret this account introduced with one of its commits.

Properties

secretIdentifier

secretIdentifier: XOTemplateSecretIdentifier;

Defined in: source/storages/types.ts:300

Template secret the value was generated for, such as someKey.

secretLookupKey

secretLookupKey: string;

Defined in: source/storages/types.ts:305

Key the secret is kept under in this account's secret store.

templateIdentifier

templateIdentifier: XOTemplateIdentifier;

Defined in: source/storages/types.ts:312

Template the secret was generated under.

Note: If a private key is derived under this template, the same stored index gives a different key under any other template.

---

StoredDefaultPolicies

type StoredDefaultPolicies = object;

Defined in: source/storages/types.ts:456

default policies for generating locking bytecode, address and change output for the entity.

Properties

change?

optional change?: object;

Defined in: source/storages/types.ts:459

Change generation policy

Name	Type	Defined in
templateIdentifier	XOTemplateIdentifier	source/storages/types.ts:461

---

StoredInvitation

type StoredInvitation = StoredArchiveFields & object;

Defined in: source/storages/types.ts:320

A stored invitation: the invitation participants share, plus fields that belong only to this account.

The shared invitation is kept whole in its own field, so the account fields are never part of what gets shared.

Type Declaration

Name	Type	Description	Defined in
createdAtTimestampMs?	number	Unix timestamp in milliseconds when this invitation was added to storage.	source/storages/types.ts:340
entityIdentifier	XOInvitationEntityIdentifier	The entity identifier of the account that is participating in the invitation.	source/storages/types.ts:330
invitation	XOInvitation	The invitation exactly as participants share it.	source/storages/types.ts:325
secretsByCommitIdentifier?	Record<XOInvitationCommitIdentifier, StoredCommitSecret[]>	Secrets this account introduced with each of its commits, keyed by commit identifier.	source/storages/types.ts:335
updatedAtTimestampMs?	number	Unix timestamp in milliseconds when the invitation was last updated in storage.	source/storages/types.ts:345

---

StoredSecretData

type StoredSecretData = SecretData & object;

Defined in: source/storages/types.ts:134

A stored secret together with the lookup key it is kept under in the secret store.

Type Declaration

Name	Type	Description	Defined in
secretLookupKey	string	Key the secret is kept under in the secret store	source/storages/types.ts:137

---

StoredTemplate

type StoredTemplate = StoredArchiveFields & object;

Defined in: source/storages/types.ts:351

A stored template: the template as imported, plus fields that belong only to this account.

Type Declaration

Name	Type	Description	Defined in
importedAtTimestampMs?	number	Unix timestamp in milliseconds when this template was imported into storage.	source/storages/types.ts:361
template	XOTemplate	The template exactly as it was imported.	source/storages/types.ts:356

---

UnspentOutputData

type UnspentOutputData = object;

Defined in: source/storages/types.ts:393

Data structure for storing unspent output information in the storage.

Properties

minedAtHeight?

optional minedAtHeight?: number;

Defined in: source/storages/types.ts:420

The block height of the block that included the transaction containing this output. Omitted when that height is unknown. The transaction may be unconfirmed, or it may already be mined in a block which is not discovered yet.

reservedBy?

optional reservedBy?: XOInvitationIdentifier;

Defined in: source/storages/types.ts:400

The invitation identifier that holds the reservation on this output. Omitted means the output is not reserved.

status

status: UnspentOutputStatus;

Defined in: source/storages/types.ts:396

The status of the unspent output

tokenAmount?

optional tokenAmount?: string;

Defined in: source/storages/types.ts:438

Fungible token amount on this UTXO. Omitted when the UTXO has no fungible token balance.

tokenCategory?

optional tokenCategory?: string;

Defined in: source/storages/types.ts:432

Token category for this UTXO. When tokenCategory is present, the UTXO is a CashToken output. When omitted, it is plain BCH only.

tokenNftCapability?

optional tokenNftCapability?: XOTemplateNftCapability;

Defined in: source/storages/types.ts:444

NFT capability on this UTXO when it carries a non-fungible token. Omitted when the UTXO has no NFT.

tokenNftCommitment?

optional tokenNftCommitment?: string;

Defined in: source/storages/types.ts:450

NFT commitment on this UTXO. Omitted when the UTXO has no NFT commitment.

---

UnspentOutputDataFilter

type UnspentOutputDataFilter = object;

Defined in: source/storages/types.ts:221

Filter options for unspent output data (applied in-memory).

Properties

reserved?

optional reserved?: boolean;

Defined in: source/storages/types.ts:224

Filter by reserved flag

tokenAmount?

optional tokenAmount?: string;

Defined in: source/storages/types.ts:234

Filter by token amount

tokenCategory?

optional tokenCategory?: string;

Defined in: source/storages/types.ts:229

Filter by token category

tokenNftCapability?

optional tokenNftCapability?: XOTemplateNftCapability;

Defined in: source/storages/types.ts:239

Filter by NFT capability

tokenNftCommitment?

optional tokenNftCommitment?: string;

Defined in: source/storages/types.ts:244

Filter by NFT commitment

---

UnspentOutputDataQuery

type UnspentOutputDataQuery = object;

Defined in: source/storages/types.ts:203

Query options for unspent output data.

Properties

templateIdentifier?

optional templateIdentifier?: XOTemplateIdentifier;

Defined in: source/storages/types.ts:206

Query by template identifier

---

UnspentOutputReservationParameters

type UnspentOutputReservationParameters = object;

Defined in: source/storages/types.ts:90

Values used to reserve or release a set of unspent outputs for one invitation.

Properties

outpoints

outpoints: Outpoint[];

Defined in: source/storages/types.ts:93

The outpoints whose reservation is updated.

---

WalletSettings

type WalletSettings = object;

Defined in: source/storages/types.ts:480

All user-configurable wallet settings persisted for this account, stored as a single record.

Properties

walletName?

optional walletName?: string;

Defined in: source/storages/types.ts:483

Human-readable name for the wallet, set by the user

---

WalletSettingsKey

type WalletSettingsKey = ValueOf<typeof WalletSettingsKeys>;

Defined in: source/storages/types.ts:501

A single field key from WalletSettingsKeys.

---

createStorageAdapter

const createStorageAdapter: (config) => Promise<XOStorage>;

Defined in: source/storages/create.ts:22

Creates a new storage adapter.

Parameters

Parameter	Type	Description
config	StorageConfig	Storage configuration options

Returns

Promise<XOStorage>

Promise that resolves to a new storage adapter instance

Throws

If the given storage type is not supported.

Warning

Currently config only controls naming. As new options are added to StorageConfig, care must be taken when passing them through here as some options may alter database behavior or break expected behavior if applied incorrectly.

---

DEFAULT_DATABASE_FILENAME

const DEFAULT_DATABASE_FILENAME: "XO" = "XO";

Defined in: source/storages/defaults.ts:9

Default base name used when no databaseFilename is provided.

---

DEFAULT_DATABASE_PATH

const DEFAULT_DATABASE_PATH: "./" = "./";

Defined in: source/storages/defaults.ts:4

Default directory used when no databasePath is provided.

---

SECRET_LOOKUP_KEY_BYTE_LENGTH

const SECRET_LOOKUP_KEY_BYTE_LENGTH: 16 = 16;

Defined in: source/storages/defaults.ts:19

Length in bytes of the random lookup key generated for each stored secret.

---

WALLET_SETTINGS_STORAGE_KEY

const WALLET_SETTINGS_STORAGE_KEY: "walletSettings" = "walletSettings";

Defined in: source/storages/defaults.ts:14

Wallet settings storage key.

---

WalletSettingsKeys

const WalletSettingsKeys: object;

Defined in: source/storages/types.ts:493

Named keys for each field on WalletSettings. This exists so that unsetting of the wallet settings can accept pre-defined identifiers.

Type Declaration

Name	Type	Defined in
DEFAULT_POLICIES	"defaultPolicies"	source/storages/types.ts:496
WALLET_NAME	"walletName"	source/storages/types.ts:496