Class Engine

XO Engine class: Acts like an orchestrator for the XO system.

Methods

acceptInvitation

acceptInvitation(
invitation: XOInvitation,
params?: AppendInvitationParameters,
): Promise<XOInvitation>
Accepts an invitation, an entity accepts an invitation and becomes part of the invitation.
Parameters
- invitation: XOInvitation
  The invitation to be accepted.
- Optionalparams: AppendInvitationParameters
  Optional parameters for accepting the invitation.
Returns Promise<XOInvitation>
The updated XOInvitation instance.

Throws
If the template is not found.

Throws
If the action is not found.

Throws
If the entity identifiers are invalid.

Throws
If the requirements are invalid.

Throws
If the commit signatures are invalid.
- Defined in source/engine.ts:419

appendInvitation

appendInvitation(
invitationIdentifier: string,
params: AppendInvitationParameters,
): Promise<XOInvitation>
Appends the invitation with the new information.
Parameters
- invitationIdentifier: string
  The identifier of the invitation to append. The invitation must already exist in the store.
- params: AppendInvitationParameters
  The parameters to append the invitation with.
Returns Promise<XOInvitation>
The appended invitation.

Throws
If the invitation is not found in the store.
- Defined in source/engine.ts:487

createInvitation

createInvitation(params: InvitationCreationParameters): Promise<XOInvitation>
Creates an invitation that can be shared with other entities, user, application, etc. Invitation is the fundamental communication unit in XO, all the interactions done using the xo template are done using invitations.
Parameters
- params: InvitationCreationParameters
  The parameters for invitation creation.
  
  Parameters required for creating a new XO invitation.
  - actionIdentifier: string
    Identifier of the action within the template to initiate.
  - templateIdentifier: string
    Identifier of the template to use for this invitation.
Returns Promise<XOInvitation>
A promise that resolves to the constructed invitation.

Throws
If the template is not found.

Throws
If the action is not found.

TODO: Add all the throws that happen during the execution of the method.
- Defined in source/engine.ts:359

executeAction

executeAction(
invitationIdentifier: string,
params: ExecuteActionParameters,
): Promise<string>
Executes an action for a given invitation.
Parameters
- invitationIdentifier: string
  The identifier of the invitation whose action to execute. The invitation must already exist in the store.
- params: ExecuteActionParameters
  Parameters for executing the action.
Returns Promise<string>
Resolves with the transaction hash when the action is executed.

Throws
If the invitation is not found in the store.

TODO: Add all the throws that happen during the execution of the method.
- Defined in source/engine.ts:738

generateLockingBytecode

generateLockingBytecode(
    templateIdentifier: string,
    outputIdentifier: string,
    roleIdentifier?: string,
): Promise<string>
Generates the locking bytecode for a specified template output and role.

Role is important because in the template definition it can direct to a different secret or a locking script for that to be discovered and used, it must know what role is provided. Also, it's important for libauth compiler to know what role is being used to generate the locking bytecode.

Currently, only "standard" type (e.g. P2PKH) locking scripts are supported. In the future, this method will be extended to support more output script types based on template definitions.

Future definition of primitives is going to define how other non-p2pkh locking scripts are validated, for example, p2pkh is possible because the engine know what a private key and public key is more such primitives will be defined and they will be helpful in generating and validating locking scripts of different types.

Process overview:
- Fetch the template and output definition by their identifiers.
- Find the relevant locking script and roles.
- Select the specified role or fallback to the first available role.
- Build the entity ownership mapping, scripts, and variable definitions for Libauth.
- Set up unlocking scripts and locking script type for the compiler configuration.
- For "standard" lock scripts, generate entropy if required. (TODO: Improve entropy generation.)
- Compile the locking bytecode with the Libauth compiler.
- Subscribe to blockchain updates for the script hash and store the resulting bytecode.
TODO: Support additional types of outputs/scripts tied to template specification. TODO: If important to make this process faster, consider emitting an event and pushing process to the event loop. TODO: Encrypt the new information, update the encrypted state servers.
Parameters
- templateIdentifier: string
  Identifier of the template.
- outputIdentifier: string
  Identifier of the output (from the template).
- OptionalroleIdentifier: string
  Role identifier (corresponding to a role in the output's script).
Returns Promise<string>
The generated locking bytecode as a hexadecimal string.

Throws
If any required template, output, or configuration is not found, or if compilation fails.
- Defined in source/engine.ts:1012

generateLockingBytecodeForDefaultParameters

generateLockingBytecodeForDefaultParameters(): Promise<string>
Generates a locking bytecode using the engine's default template, output, and role identifiers.

Returns Promise<string>
A promise that resolves to the generated locking bytecode as a string.
- Defined in source/engine.ts:1168

generateLockingDataForStandardP2PKH

generateLockingDataForStandardP2PKH(
    templateIdentifier: string,
    outputIdentifier: string,
    roleIdentifier: string,
    lockingScriptForOutput: XOTemplateLockingScript,
): Promise<
    {
        derivativeIndex: string;
        lockingData: PrivateKeyRecordForLibauthCompiler;
    },
>
Generate locking data and derivative index for P2PKH.
Parameters
- templateIdentifier: string
- outputIdentifier: string
- roleIdentifier: string
- lockingScriptForOutput: XOTemplateLockingScript
Returns Promise<
    {
        derivativeIndex: string;
        lockingData: PrivateKeyRecordForLibauthCompiler;
    },
>
- Defined in source/engine.ts:1175

getChainStatus

getChainStatus(): Promise<ChainStatus>
Retrieves the current chain status from the electrum application.

Returns Promise<ChainStatus>
The current chain status.
- Defined in source/engine.ts:189

getInvitationOrThrow

getInvitationOrThrow(invitationIdentifier: string): Promise<StoredInvitation>
Fetches a stored invitation by identifier
Parameters
- invitationIdentifier: string
  The identifier to look up.
Returns Promise<StoredInvitation>
The stored invitation, or undefined.
- Defined in source/engine.ts:1207

getSpendableResources

getSpendableResources(
invitation: XOInvitation,
options?: GetSpendableResourcesParameters,
): Promise<{ unspentOutputs: (...)[] }>
Finds suitable resources for an invitation.

TODO: May become private. This may change in the future and become a more advanced coin selection method used directly by the engine. The current behavior is that it finds "spendable" outputs, but we may adjust this to actually find "suitable" outputs.
Parameters
- invitation: XOInvitation
  The invitation to find resources for.
- Optionaloptions: GetSpendableResourcesParameters
  Parameters for finding suitable resources.
Returns Promise<{ unspentOutputs: (...)[] }>
The list of suitable resources.
- Defined in source/engine.ts:884

getTemplate

getTemplate(templateIdentifier: string): Promise<XOTemplate>
Retrieves a template by its identifier from the state.
Parameters
- templateIdentifier: string
  Template identifier.
Returns Promise<XOTemplate>
The template object.
- Defined in source/engine.ts:202

getTemplateOrThrow

getTemplateOrThrow(templateIdentifier: string): Promise<XOTemplate>
Fetches a stored template by identifier
Parameters
- templateIdentifier: string
  The identifier to look up.
Returns Promise<XOTemplate>
The stored template.
- Defined in source/engine.ts:1224

importTemplate

importTemplate(
untrustedJsonOrObject: string | XOTemplate,
): Promise<{ template: XOTemplate; templateIdentifier: string }>
Imports a template into the Engine after sanitization and validation.
Parameters
- untrustedJsonOrObject: string | XOTemplate
  JSON or object containing the untrusted template to import.
Returns Promise<{ template: XOTemplate; templateIdentifier: string }>
Resolves when the template is imported.

Throws
If the template is invalid.
- Defined in source/engine.ts:213

initializeStateSync

initializeStateSync(): Promise<void>
TODO: Implement this.

State sync should always be working, any hiccups in the sync process should be resolved Unable to do so should halt all operations unless no remote servers are provided.

Initializes the state sync process.

Returns Promise<void>
Resolves when the state sync is initialized.
- Defined in source/engine.ts:327

listAvailableRoles

listAvailableRoles(invitation: XOInvitation): Promise<string[]>
Lists available roles for the given invitation.
Parameters
- invitation: XOInvitation
  The invitation to examine.
Returns Promise<string[]>
The list of roles that still require data.

Throws
If the template is not found.

Throws
If the action is not found.
- Defined in source/engine.ts:811

listImportedTemplates

listImportedTemplates(): Promise<XOTemplate[]>
Lists all the imported templates.

Returns Promise<XOTemplate[]>
The list of imported templates.
- Defined in source/engine.ts:232

listMissingRequirements

listMissingRequirements(
invitationIdentifier: string,
): Promise<XOInvitationRequirements>
Lists missing requirements for the provided invitation.
Parameters
- invitationIdentifier: string
  The identifier of the invitation to analyze. The invitation must already exist in the store.
Returns Promise<XOInvitationRequirements>
The missing requirements.

Throws
If the invitation is not found in the store.
- Defined in source/engine.ts:847

listRequirements

listRequirements(invitation: XOInvitation): Promise<XOInvitationRequirements>
Lists requirements for the provided invitation.
Parameters
- invitation: XOInvitation
  The invitation to analyze requirements for.
Returns Promise<XOInvitationRequirements>
The requirements information.
- Defined in source/engine.ts:829

listScriptHashes

listScriptHashes(): Promise<ScriptHashData[]>
Gets all the script hashes from all the templates.

Returns Promise<ScriptHashData[]>
An array of script hash data objects.
- Defined in source/engine.ts:961

listScriptHashesForTemplate

listScriptHashesForTemplate(
templateIdentifier: string,
): Promise<ScriptHashData[]>
Retrieves a list of script hash data stored for a given template identifier.
Parameters
- templateIdentifier: string
  The identifier of the template.
Returns Promise<ScriptHashData[]>
An array of script hash data objects.
- Defined in source/engine.ts:952

listStartingActions

listStartingActions(
templateIdentifier: string,
): Promise<XOTemplateActionIntent[]>
Lists the starting actions available in a specified template.
Parameters
- templateIdentifier: string
  Template identifier.
Returns Promise<XOTemplateActionIntent[]>
The list of starting actions.
- Defined in source/engine.ts:241

listUnspentOutputsData

listUnspentOutputsData(): Promise<UnspentOutputData[]>
Lists all the unspent outputs.

Returns Promise<UnspentOutputData[]>
The list of unspent outputs.
- Defined in source/engine.ts:870

setDefaultLockingParameters

setDefaultLockingParameters(
    templateIdentifier: string,
    outputIdentifier: string,
    roleIdentifier: string,
): Promise<void>
TENTATIVE METHOD: DEFAULT LOCKING STRATEGY UNKNOWN

Sets the default locking parameters (template, output, and role identifiers) for the engine. TODO: The default identifiers exist as the strategy on how to create the change and default unlocking conditions are unclear. This is likely to change in the future.
Parameters
- templateIdentifier: string
  The identifier of the template to use as default.
- outputIdentifier: string
  The identifier of the output within the specified template.
- roleIdentifier: string
  The identifier of the role to use as default for this output.
Returns Promise<void>
Resolves when the default parameters have been successfully set.

Throws
If the template or output cannot be found.
- Defined in source/engine.ts:308

signInvitation

signInvitation(invitationIdentifier: string): Promise<XOInvitation>
Signs the provided invitation once all the resources are reserved and the invitation is complete. This method is used to sign own inputs and provide unlocking data for them, this appends the invitation and adds new commit with unlocking data.
Parameters
- invitationIdentifier: string
  The identifier of the invitation to sign. The invitation must already exist in the store.
Returns Promise<XOInvitation>
Resolves when signing is complete.

Throws
If the invitation is not found in the store.

TODO: Add all the throws that happen during the execution of the method.
- Defined in source/engine.ts:505

stop

stop(): Promise<void>
Stops the engine instance and cleans up resources.

Returns Promise<void>
Resolves when the engine is stopped.
- Defined in source/engine.ts:172

subscribeToScriptHashForTemplate

subscribeToScriptHashForTemplate(templateIdentifier: string): Promise<void>
Subscribe to the script hashes for a template.

TODO: Make this a private/internal method. We may change how/where this is defined in the future. We'd like to ensure events are propagated to the sync server with an ACK and that the states match between remote and local.
Parameters
- templateIdentifier: string
  Template identifier.
Returns Promise<void>
Resolves when the script hashes are subscribed.
- Defined in source/engine.ts:272

updateUnspentOutputsForScriptHashInStore

updateUnspentOutputsForScriptHashInStore(scriptHash: string): Promise<void>
Synchronizes the store of unspent outputs for a given script hash with the current state of the blockchain.

This method performs the following:
1. Retrieves the stored script hash data from the store.
2. Fetches the current list of unspent outputs for the script hash from the store.
3. Computes the corresponding scripthash from the script hash.
4. Queries the blockchain for all unspent transaction outputs associated with the scripthash.
5. Adds any new unspent outputs found on the blockchain but missing from the store to the store.
6. Removes any unspent outputs present in the store but no longer in the blockchain.
Parameters
- scriptHash: string
  The script hash for which to update the stored unspent outputs.
Returns Promise<void>
Throws
If the script hash is not found in the store.
- Defined in source/engine.ts:1249

updateUnspentOutputsForTemplate

updateUnspentOutputsForTemplate(templateIdentifier: string): Promise<void>
Update the unspent outputs for all of a templates lockingBytecodes.

TODO: Make this an private/internal method.
Parameters
- templateIdentifier: string
  Template identifier.
Returns Promise<void>
Resolves when the unspent outputs are updated.
- Defined in source/engine.ts:256

`Static`create

create(mnemonic: string, options: XOEngineOptions): Promise<Engine>
Initializes and creates a new XO Engine instance. Configures the state, initializes the sync server and monitor for app and blockchain events
Parameters
- mnemonic: string
  BIP39 mnemonic to be used for this instance of the engine.
- options: XOEngineOptions
  Database configuration options.
Returns Promise<Engine>
An initialized Engine instance.
- Defined in source/engine.ts:133

Class Engine

Index

Methods

Methods

acceptInvitation

Parameters

Returns Promise<XOInvitation>

Throws

Throws

Throws

Throws

Throws

appendInvitation

Parameters

Returns Promise<XOInvitation>

Throws

createInvitation

Parameters

actionIdentifier: string

templateIdentifier: string

Returns Promise<XOInvitation>

Throws

Throws

executeAction

Parameters

Returns Promise<string>

Throws

generateLockingBytecode

Parameters

Returns Promise<string>

Throws

generateLockingBytecodeForDefaultParameters

Returns Promise<string>

generateLockingDataForStandardP2PKH

Parameters

Returns Promise< { derivativeIndex: string; lockingData: PrivateKeyRecordForLibauthCompiler; },>

getChainStatus

Returns Promise<ChainStatus>

getInvitationOrThrow

Parameters

Returns Promise<StoredInvitation>

getSpendableResources

Parameters

Returns Promise<{ unspentOutputs: (...)[] }>

getTemplate

Parameters

Returns Promise<XOTemplate>

getTemplateOrThrow

Parameters

Returns Promise<XOTemplate>

importTemplate

Parameters

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

Throws

initializeStateSync

Returns Promise<void>

listAvailableRoles

Parameters

Returns Promise<string[]>

Throws

Throws

listImportedTemplates

Returns Promise<XOTemplate[]>

listMissingRequirements

Parameters

Returns Promise<XOInvitationRequirements>

Throws

listRequirements

Parameters

Returns Promise<XOInvitationRequirements>

listScriptHashes

Returns Promise<ScriptHashData[]>

listScriptHashesForTemplate

Parameters

Returns Promise<ScriptHashData[]>

listStartingActions

Parameters

Returns Promise<XOTemplateActionIntent[]>

listUnspentOutputsData

Returns Promise<UnspentOutputData[]>

Returns Promise<
{
derivativeIndex: string;
lockingData: PrivateKeyRecordForLibauthCompiler;
},
>

`Static`create