@xo-cash/types

XO type definitions and interfaces

⚠️ 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

Installation

bash

npm install @xo-cash/types

Usage

typescript

import { XOInvitation, XOTemplate } from '@xo-cash/types';

Development

Formatting

Run npm run style to format code. This command runs Prettier first, then ESLint with --fix.

Note: Prettier adjusts comment formatting, which conflicts with our ESLint lines-around-comment rule. Running ESLint after Prettier restores the preferred comment formatting.

License

MIT - See LICENSE for details.

BchVmVersion

type BchVmVersion = ValueOf<typeof BchVmVersions>;

Defined in: source/template.ts:33

The set of BCH VM versions that an XO template can declare support for.

FungibleTokenAmount

type FungibleTokenAmount = bigint;

Defined in: source/template.ts:15

A fungible token amount.

OutputNft

type OutputNft = NonNullable<OutputToken["nft"]>;

Defined in: source/invitation.ts:314

The NFT fields of an output.

OutputToken

type OutputToken = NonNullable<Output["token"]>;

Defined in: source/invitation.ts:309

The token fields of an output.

Satoshis

type Satoshis = bigint;

Defined in: source/template.ts:10

Type for satoshis.

ValueOf

type ValueOf<T> = T[keyof T];

Defined in: source/utilities.ts:17

Union of all property values in an object type.

Use this to derive a string literal union from a runtime const object declared with as const.

Type Parameters

Type Parameter
`T`

Example

export const XOTemplateLockingTypes = {
    P2S: 'p2s',
    P2PKH: 'p2pkh',
    P2SH: 'p2sh',
} as const;

export type XOTemplateLockingType = ValueOf<typeof XOTemplateLockingTypes>;
// 'p2s' | 'p2pkh' | 'p2sh'

XOInvitation

type XOInvitation = object;

Defined in: source/invitation.ts:708

An invitation shared among participants in the XO stack.

{
  "invitationIdentifier": "...",
  "templateIdentifier": "...",
  "actionIdentifier": "...",
  ...
  "commits": [
    {
      "commitIdentifier": "...",
      ...
    },
    {
      "commitIdentifier": "...",
      ...
    }
  ],
  "result": {
    "transactions": { },
    "data": { }
  }
}  ← this type

Properties

actionIdentifier

actionIdentifier: XOTemplateActionIdentifier;

Defined in: source/invitation.ts:728

The action identifier.

commits

commits: XOInvitationCommit[];

Defined in: source/invitation.ts:733

The commits in the invitation.

createdAtTimestamp

createdAtTimestamp: XOInvitationTimestamp;

Defined in: source/invitation.ts:718

The timestamp when the invitation was created.

invitationIdentifier

invitationIdentifier: XOInvitationIdentifier;

Defined in: source/invitation.ts:713

The invitation identifier for the invitation.

result?

optional result?: XOInvitationResult;

Defined in: source/invitation.ts:738

Result of the invitation process

templateIdentifier

templateIdentifier: XOTemplateIdentifier;

Defined in: source/invitation.ts:723

The template identifier.

XOInvitationActionReference

type XOInvitationActionReference = object;

Defined in: source/invitation.ts:96

Pair of template and action identifiers used to resolve a template action for an invitation commit.

{
  "invitationIdentifier": "...",
  ...
  "commits": [
    {
      "commitIdentifier": "...",
      "actionReference": {
        "templateIdentifier": "...",
        "actionIdentifier": "..."
      }  ← this type
      ...
    }
    ...
  ]
}

Properties

actionIdentifier

actionIdentifier: XOTemplateActionIdentifier;

Defined in: source/invitation.ts:106

The action within that template.

templateIdentifier

templateIdentifier: XOTemplateIdentifier;

Defined in: source/invitation.ts:101

The template that defines the action.

XOInvitationCommit

type XOInvitationCommit = object;

Defined in: source/invitation.ts:489

A signed commit in an invitation history chain.

{
  "invitationIdentifier": "...",
  ...
  "commits": [
    {
      "commitIdentifier": "...",
      "createdAtTimestamp": 1717000000000,
      "memo": "Invoice 1042",
      ...
    }  ← this type
    ...
  ]
}

Properties

actionReference?

optional actionReference?: XOInvitationActionReference;

Defined in: source/invitation.ts:515

When set, the engine resolves the template action from these identifiers for this commit. When omitted, it uses the invitation root templateIdentifier and actionIdentifier.

commitIdentifier

commitIdentifier: XOInvitationCommitIdentifier;

Defined in: source/invitation.ts:494

The commit identifier for this commit.

createdAtTimestamp

createdAtTimestamp: XOInvitationTimestamp;

Defined in: source/invitation.ts:509

When this commit was created.

data

data: XOInvitationCommitData;

Defined in: source/invitation.ts:520

The data provided by this commit.

entityIdentifier

entityIdentifier: XOInvitationEntityIdentifier;

Defined in: source/invitation.ts:504

The entity identifier that made this commit.

expiresAtTimestamp

expiresAtTimestamp: XOInvitationTimestamp;

Defined in: source/invitation.ts:530

Expiration timestamp for this specific commit.

memo?

optional memo?: XOInvitationMemo;

Defined in: source/invitation.ts:535

Optional note from the entity.

previousCommitIdentifier

previousCommitIdentifier: 
  | XOInvitationCommitIdentifier
  | undefined;

Defined in: source/invitation.ts:499

The identifier of the previous commit.

signature

signature: XOInvitationSignature;

Defined in: source/invitation.ts:525

Signature of the entity committing this data.

XOInvitationCommitData

type XOInvitationCommitData = object;

Defined in: source/invitation.ts:425

Payload provided by a single invitation commit.

{
  "invitationIdentifier": "...",
  ...
  "commits": [
    {
      "commitIdentifier": "...",
      "data": { }  ← this type
      ...
    }
    ...
  ]
}

Properties

inputs?

optional inputs?: XOInvitationInput[];

Defined in: source/invitation.ts:445

Transaction inputs provided in this commit.

outputs?

optional outputs?: XOInvitationOutput[];

Defined in: source/invitation.ts:450

Transaction outputs provided in this commit.

resolutions?

optional resolutions?: XOInvitationResolution[];

Defined in: source/invitation.ts:455

Public keys, data signatures or other partially resolved evaluations resolved in this commit.

roleIdentifier?

optional roleIdentifier?: XOTemplateRoleIdentifier;

Defined in: source/invitation.ts:460

The role the committing entity takes in the action with this commit.

transactionLocktime?

optional transactionLocktime?: XOInvitationTransactionLocktime;

Defined in: source/invitation.ts:435

The locktime for the transaction.

transactionVersion?

optional transactionVersion?: XOInvitationTransactionVersion;

Defined in: source/invitation.ts:430

The version of the transaction.

variables?

optional variables?: XOInvitationVariable[];

Defined in: source/invitation.ts:440

Variables provided in this commit.

XOInvitationCommitDataItemIndex

type XOInvitationCommitDataItemIndex = number;

Defined in: source/invitation.ts:42

Index of an item within a commit data array. Used in mergesWith.itemIndex to locate the referenced item.

XOInvitationCommitIdentifier

type XOInvitationCommitIdentifier = string;

Defined in: source/invitation.ts:22

Commit Identifier within an invitation.

XOInvitationDataResult

type XOInvitationDataResult = object;

Defined in: source/invitation.ts:621

Result for a completed invitation process that resulted in a data field.

{
  "data": {
    "messageSignature": {
      "value": "..."
    }  ← this type
  }
}

Properties

createdAtTimestamp

createdAtTimestamp: XOInvitationTimestamp;

Defined in: source/invitation.ts:631

Timestamp when the data was created.

createdByEntityIdentifier

createdByEntityIdentifier: XOInvitationEntityIdentifier;

Defined in: source/invitation.ts:636

The entity identifier that created this data.

createdBySignature

createdBySignature: XOInvitationSignature;

Defined in: source/invitation.ts:641

Signature of the entity that created this data.

value

value: XOInvitationVariableValue;

Defined in: source/invitation.ts:626

Resolved value for the data.

XOInvitationEntityIdentifier

type XOInvitationEntityIdentifier = string;

Defined in: source/invitation.ts:27

Entity Identifier identifying an entity that signed an invitation commit.

XOInvitationIdentifier

type XOInvitationIdentifier = string;

Defined in: source/invitation.ts:17

Identifier for an XO invitation.

XOInvitationInput

type XOInvitationInput = Partial<Input> & object;

Defined in: source/invitation.ts:278

A transaction input provided in a commit.

{
  "invitationIdentifier": "...",
  ...
  "commits": [
    {
      "commitIdentifier": "...",
      "data": {
        "inputs": [
          {
            "inputIdentifier": "...",
            "transactionIndex": 0
          }  ← this type
        ]
      }
      ...
    }
    ...
  ]
}

Type Declaration

Name	Type	Description	Defined in
`inputIdentifier?`	`XOTemplateInputIdentifier`	The identifier of this input.	source/invitation.ts:283
`mergesWith?`	`XOInvitationMergesWithReference`	Reference to an input in an earlier commit that this input extends.	source/invitation.ts:303
`resolutions?`	`XOInvitationResolution`[]	Signatures or partially resolved evaluations for this input, used to build its unlocking bytecode once all are present.	source/invitation.ts:298
`roleIdentifier?`	`XOTemplateRoleIdentifier`	The role identifier this input belongs to.	source/invitation.ts:293
`transactionIndex?`	`XOInvitationTransactionInputIndex`	The position/index this input should occupy in the final transaction.	source/invitation.ts:288

XOInvitationMemo

type XOInvitationMemo = string;

Defined in: source/invitation.ts:468

Human readable note attached to a commit so participants can coordinate better or just general notes.

Note: When present, the engine includes the memo in the commit signing payload so peers can trust the text.

XOInvitationMergesWithReference

type XOInvitationMergesWithReference = object;

Defined in: source/invitation.ts:136

Reference to an item in an earlier commit that a variable, input, or output extends.

{
  "invitationIdentifier": "...",
  ...
  "commits": [
    {
      "commitIdentifier": "...",
      "data": {
        "variables|inputs|outputs": [
          {
            "mergesWith": {
              "commitIdentifier": "...",
              "itemIndex": 0
            }  ← this type
          }
        ]
      }
      ...
    }
    ...
  ]
}

Properties

commitIdentifier

commitIdentifier: XOInvitationCommitIdentifier;

Defined in: source/invitation.ts:141

Identifier of the earlier commit that contains the item being extended.

itemIndex

itemIndex: XOInvitationCommitDataItemIndex;

Defined in: source/invitation.ts:154

Together with commitIdentifier, this identifies the exact item to extend when a later commit supplies information that was not added earlier. For example, when an input was already provided without unlockingBytecode, a follow up commit can add a new input entry with mergesWith, itemIndex and unlockingBytecode. The merger then uses this index to locate that earlier input and populate the missing field without replacing the commit.

This variable is named 'item' because it's used with variables, inputs and outputs.

Note: The index starts at 0 for the first item in the commit data array.

XOInvitationOutput

type XOInvitationOutput = Omit<Partial<Output>, "token"> & object;

Defined in: source/invitation.ts:374

A transaction output provided in a commit.

{
  "invitationIdentifier": "...",
  ...
  "commits": [
    {
      "commitIdentifier": "...",
      "data": {
        "outputs": [
          {
            "outputIdentifier": "...",
            "transactionIndex": 0
          }  ← this type
        ]
      }
      ...
    }
    ...
  ]
}

Type Declaration

Name	Type	Description	Defined in
`mergesWith?`	`XOInvitationMergesWithReference`	Reference to an output in an earlier commit that this output extends.	source/invitation.ts:404
`outputIdentifier?`	`XOTemplateOutputIdentifier`	The identifier of this output.	source/invitation.ts:384
`roleIdentifier?`	`XOTemplateRoleIdentifier`	The role identifier this output belongs to.	source/invitation.ts:399
`secretIdentifier?`	`XOTemplateSecretIdentifier`	The secret identifier of this output.	source/invitation.ts:394
`token?`	`XOInvitationToken`	CashToken fields. Any field may be optional until a later commit supplies it.	source/invitation.ts:379
`transactionIndex?`	`XOInvitationTransactionOutputIndex`	The position/index this output should occupy in the final transaction.	source/invitation.ts:389

XOInvitationRequirements

type XOInvitationRequirements = XOInvitationRoleRequirement & object;

Defined in: source/invitation.ts:169

The requirements for an invitation with a role.

Type Declaration

Name	Type	Defined in
`roles?`	`Record`<`XOTemplateRoleIdentifier`, `XOInvitationRoleRequirement`>	source/invitation.ts:170

XOInvitationResolution

type XOInvitationResolution = object;

Defined in: source/invitation.ts:235

A partially resolved evaluation provided by a commit. These can be used to compile scripts that use the value without holding it.

Properties

resolutionIdentifier

resolutionIdentifier: XOInvitationResolutionIdentifier;

Defined in: source/invitation.ts:240

The identifier of the operation this value resolves.

roleIdentifier?

optional roleIdentifier?: XOTemplateRoleIdentifier;

Defined in: source/invitation.ts:250

The role this value was resolved from.

value

value: Uint8Array;

Defined in: source/invitation.ts:245

The resolved bytes, such as a public key or a signature.

XOInvitationResolutionIdentifier

type XOInvitationResolutionIdentifier = string;

Defined in: source/invitation.ts:230

CashAssembly identifier of an operation on an evaluation, such as someKey.public_key or someKey.schnorr_signature.all_outputs.

XOInvitationResult

type XOInvitationResult = object;

Defined in: source/invitation.ts:667

Result of a completed invitation. An invitation may produce one or more transactions or data fields.

{
  "invitationIdentifier": "...",
  ...
  "result": {
    "transactions": {
      "requestSatoshisTransaction": {
        "transactionHash": "...",
        "transactionHex": "..."
      },
    },
    "data": {
      "messageSignature": {
        "value": "..."
      }
    }
  }  ← this type
}

Properties

data?

optional data?: Record<XOTemplateDataIdentifier, XOInvitationDataResult>;

Defined in: source/invitation.ts:679

Data resulting from the invitation process.

transactions?

optional transactions?: Record<XOTemplateTransactionIdentifier, XOInvitationTransactionResult>;

Defined in: source/invitation.ts:674

Transactions resulting from the invitation process.

Note: The existing workflow does not support multiple transactions, but this structure already supports it.

XOInvitationRoleRequirement

type XOInvitationRoleRequirement = object;

Defined in: source/invitation.ts:160

The requirements for an invitation.

XOInvitationSignature

type XOInvitationSignature = string;

Defined in: source/invitation.ts:50

Signature of the entity producing a commit or result.

commit.signature: Signature of the entity that made the commit, including data, createdAtTimestamp, and optional memo.
result.createdBySignature: Signature of the entity that created the transaction before broadcasting or produced data.
result.broadcastedBySignature: Signature of the entity that broadcasted the transaction.

XOInvitationTimestamp

type XOInvitationTimestamp = number;

Defined in: source/invitation.ts:58

Timestamps in an invitation e.g.

createdAtTimestamp: When the invitation, commit, or result was created.
expiresAtTimestamp: When the commit expires.
broadcastedAtTimestamp: When the transaction was broadcasted.

XOInvitationToken

type XOInvitationToken = object;

Defined in: source/invitation.ts:320

A commit may supply any subset of the following fields, hence not using the Output type or Output['token'] type.

Properties

amount?

optional amount?: OutputToken["amount"];

Defined in: source/invitation.ts:325

Fungible token amount. Omitted until a commit supplies it.

category?

optional category?: OutputToken["category"];

Defined in: source/invitation.ts:330

Token category bytes. Omitted until a commit supplies them.

nft?

optional nft?: object;

Defined in: source/invitation.ts:335

NFT fields. Omitted when the output carries fungible tokens only.

Name	Type	Description	Defined in
`capability?`	`OutputNft`[`"capability"`]	NFT capability. Omitted until a commit supplies it.	source/invitation.ts:340
`commitment?`	`OutputNft`[`"commitment"`]	NFT commitment bytes. Omitted until a commit supplies them.	source/invitation.ts:345

XOInvitationTransactionBroadcastDetails

type XOInvitationTransactionBroadcastDetails = object;

Defined in: source/invitation.ts:569

The broadcast fields added once the transaction has been submitted to the network.

Properties

broadcastedAtTimestamp

broadcastedAtTimestamp: XOInvitationTimestamp;

Defined in: source/invitation.ts:574

Timestamp when the transaction was broadcasted.

broadcastedByEntityIdentifier

broadcastedByEntityIdentifier: XOInvitationEntityIdentifier;

Defined in: source/invitation.ts:579

The entity identifier that broadcasted the transaction.

broadcastedBySignature

broadcastedBySignature: XOInvitationSignature;

Defined in: source/invitation.ts:587

Signature of the entity that broadcasted the transaction.

Note: The signature should cover the transaction data, the timestamp, entity details that created the transaction and the entity details that broadcasts the transaction.

XOInvitationTransactionHash

type XOInvitationTransactionHash = string;

Defined in: source/invitation.ts:63

The Hash of a Transaction.

XOInvitationTransactionInputIndex

type XOInvitationTransactionInputIndex = number;

Defined in: source/invitation.ts:32

The position/index that the input should occupy in the final transaction structure produced by the invitation.

XOInvitationTransactionLocktime

type XOInvitationTransactionLocktime = number;

Defined in: source/invitation.ts:73

The transaction locktime in the final transaction structure produced by the invitation.

XOInvitationTransactionOutputIndex

type XOInvitationTransactionOutputIndex = number;

Defined in: source/invitation.ts:37

The position/index that the output should occupy in the final transaction structure produced by the invitation.

XOInvitationTransactionResult

type XOInvitationTransactionResult = 
  | XOInvitationTransactionResultBase
  | XOInvitationTransactionResultBase & XOInvitationTransactionBroadcastDetails;

Defined in: source/invitation.ts:605

Result for a completed invitation process that resulted in a transaction.

{
  "transactions": {
    "requestSatoshisTransaction": {
      "transactionHash": "..."
    }  ← this type
  }
}

Note: The broadcast fields are either all present or all absent.

XOInvitationTransactionVersion

type XOInvitationTransactionVersion = number;

Defined in: source/invitation.ts:68

The transaction version in the final transaction structure produced by the invitation.

XOInvitationVariable

type XOInvitationVariable = object;

Defined in: source/invitation.ts:203

A variable provided in a commit.

{
  "invitationIdentifier": "...",
  ...
  "commits": [
    {
      "commitIdentifier": "...",
      "data": {
        "variables": [
          {
            "variableIdentifier": "...",
            "value": "..."
          }  ← this type
        ]
      }
      ...
    }
    ...
  ]
}

Properties

mergesWith?

optional mergesWith?: XOInvitationMergesWithReference;

Defined in: source/invitation.ts:223

Reference to a variable in an earlier commit that this variable extends.

roleIdentifier?

optional roleIdentifier?: XOTemplateRoleIdentifier;

Defined in: source/invitation.ts:218

The role identifier this variable belongs to.

value

value: XOInvitationVariableValue;

Defined in: source/invitation.ts:213

The value of this variable.

variableIdentifier

variableIdentifier: XOTemplateVariableIdentifier;

Defined in: source/invitation.ts:208

The identifier of this variable.

XOInvitationVariableValue

type XOInvitationVariableValue = bigint | boolean | number | string;

Defined in: source/invitation.ts:176

The value of a variable in an invitation.

XOTemplate

type XOTemplate = XOTemplateViewProperties & object;

Defined in: source/template.ts:862

The XO Template.

Type Declaration

Name	Type	Description	Defined in
`$schema`	`string`	The URI that identifies the JSON Schema used by this template. This enables documentation, autocompletion, and validation in JSON documents.	source/template.ts:868
`actions`	`Record`<`XOTemplateActionIdentifier`, `XOTemplateAction`>	The actions defined in this template.	source/template.ts:898
`constants?`	`Record`<`XOTemplateConstantIdentifier`, `XOTemplateConstant`>	The constants defined in this template.	source/template.ts:934
`data?`	`Record`<`XOTemplateDataIdentifier`, `XOTemplateData`>	The data fields defined in this template.	source/template.ts:903
`defaults?`	`XOTemplateDefaults`	Optional default settings used in this template.	source/template.ts:883
`icons?`	`XOTemplateIcon`[]	The icons available for use throughout the template.	source/template.ts:949
`inputs`	`Record`<`XOTemplateInputIdentifier`, `XOTemplateInput`>	The inputs defined in this template.	source/template.ts:913
`lockingScripts`	`Record`<`XOTemplateLockingScriptIdentifier`, `XOTemplateLockingScript`>	The locking script templates defined in this template.	source/template.ts:923
`outputs`	`Record`<`XOTemplateOutputIdentifier`, `XOTemplateOutput`>	The outputs defined in this template.	source/template.ts:918
`resources?`	`XOTemplateResource`[]	Resource references providing external documentation or tooling links.	source/template.ts:944
`roles`	`Record`<`XOTemplateRoleIdentifier`, `XOTemplateViewProperties`>	The roles defined in this template.	source/template.ts:888
`scenarios?`	`unknown`	The scenarios defined in this template.	source/template.ts:954
`scripts`	`Record`<`XOTemplateScriptIdentifier`, `string`>	The scripts used in this template, The keys are identifiers of the scripts and the values are the bytecode or cashASM expressions.	source/template.ts:929
`start`	`XOTemplateActionIntent`[]	A list of entry points defining which actions are available at the start.	source/template.ts:893
`supported`	`BchVmVersion`[]	The BCH VM versions that this template supports. At least one version is required.	source/template.ts:878
`transactions?`	`Record`<`XOTemplateTransactionIdentifier`, `XOTemplateTransaction`>	The transaction templates defined in this template.	source/template.ts:908
`variables?`	`Record`<`XOTemplateVariableIdentifier`, `XOTemplateVariable`>	The variables that must be provided for use in the template's scripts.	source/template.ts:939
`version?`	`string`	A string identifying the version of this template.	source/template.ts:873

XOTemplateAction

type XOTemplateAction = XOTemplateViewProperties & object;

Defined in: source/template.ts:335

An action within a template.

Type Declaration

Name	Type	Description	Defined in
`conditions?`	`string`[]	Conditions that must be met for this action to be available. Todo More work needs to be done on this field.	source/template.ts:352
`data?`	`XOTemplateDataIdentifier`	The identifier of the data field this action produces, referencing an entry in the template's data. Todo More work needs to be done on this field.	source/template.ts:366
`requirements?`	`XOTemplateActionRequirements`	The requirements for this action.	source/template.ts:345
`roles?`	`Record`<`XOTemplateRoleIdentifier`, `XOTemplateActionRole`>	Specific context for each role participating in this action.	source/template.ts:340
`transaction?`	`XOTemplateTransactionIdentifier`	The identifier of the transaction this action produces, referencing an entry in the template's transactions.	source/template.ts:358

XOTemplateActionIdentifier

type XOTemplateActionIdentifier = string;

Defined in: source/template.ts:107

Identifies an action defined in the template's actions.

XOTemplateActionIntent

type XOTemplateActionIntent = XOTemplateIntent & object;

Defined in: source/template.ts:209

An intent that targets a specific action.

Type Declaration

Name	Type	Description	Defined in
`action`	`XOTemplateActionIdentifier`	The identifier for the intended action.	source/template.ts:214

XOTemplateActionRequirements

type XOTemplateActionRequirements = object;

Defined in: source/template.ts:314

Requirements for an action. Declares which roles must participate and what secrets must be available.

Properties

participants?

optional participants?: XOTemplateRoleSlot[];

Defined in: source/template.ts:324

The participants required for this action.

secrets?

optional secrets?: XOTemplateSecretIdentifier[];

Defined in: source/template.ts:329

The secrets required for this action.

variables?

optional variables?: XOTemplateVariableIdentifier[];

Defined in: source/template.ts:319

List of variable identifiers required for this action.

XOTemplateActionRole

type XOTemplateActionRole = Partial<XOTemplateViewProperties> & object;

Defined in: source/template.ts:263

A role specific definition within an action.

Type Declaration

Name	Type	Description	Defined in
`generate?`	`string`[]	Identifiers for data items that should be generated for this role when participating in the action.	source/template.ts:269
`requirements?`	`XOTemplateActionRoleRequirements`	The requirements for this role within this action.	source/template.ts:274

XOTemplateActionRoleRequirements

type XOTemplateActionRoleRequirements = object;

Defined in: source/template.ts:247

Requirements for a specific role within an action. Describes what data or secrets the role must provide when participating.

Properties

secrets?

optional secrets?: XOTemplateSecretIdentifier[];

Defined in: source/template.ts:257

List of secret identifiers required for this role.

variables?

optional variables?: XOTemplateVariableIdentifier[];

Defined in: source/template.ts:252

List of variable identifiers required for this role.

XOTemplateAssetAmounts

type XOTemplateAssetAmounts = object;

Defined in: source/template.ts:414

Asset amounts configuration. Used for balance tracking on locking scripts and their roles, and for omitting change amounts. All fields are optional. Values may be literal amounts or CashASM expressions resolving to amounts.

Properties

fungibleTokens?

optional fungibleTokens?: FungibleTokenAmount | string | true;

Defined in: source/template.ts:430

The fungible token amount.

FungibleTokenAmount: A specific bigint amount.
string: A CashASM expression that resolves to the amount.
true: all, i.e. the entire amount

nonfungibleTokens?

optional nonfungibleTokens?: true | 0 | 1 | string;

Defined in: source/template.ts:442

Whether a non-fungible token is present (0 for absent, 1 for present), or a CashASM expression that evaluates to 0 or 1.

true: resolves to 1 if an NFT is present, or 0 if none is present. Use this when the NFT is optional, to express that the NFT is estimated to be part of the balance if present, or absent from it if not.
0: None, i.e. nothing is expected to be included
1: present and complete, as value > 1 does not make sense for non-fungible tokens
string: A CashASM expression that evaluates to 0 or 1.

satoshis?

optional satoshis?: Satoshis | string | true;

Defined in: source/template.ts:422

The satoshi amount.

Satoshis: A specific bigint amount.
string: A CashASM expression that resolves to the amount.
true: all, i.e. the entire amount

XOTemplateConstant

type XOTemplateConstant = XOTemplateViewProperties & object;

Defined in: source/template.ts:731

A constant value definition in the template.

Type Declaration

Name	Type	Description	Defined in
`hint?`	`unknown`	An optional hint to help apps and users understand what this constant represents.	source/template.ts:746
`type`	`XOTemplatePrimitiveType`	The data type of this constant.	source/template.ts:736
`value`	`unknown`	The value of this constant.	source/template.ts:741

XOTemplateConstantIdentifier

type XOTemplateConstantIdentifier = string;

Defined in: source/template.ts:128

Identifies a constant defined in the template's constants.

XOTemplateData

type XOTemplateData = object;

Defined in: source/template.ts:784

A data field definition in the template.

Todo

More work needs to be done on this type.

Properties

hint?

optional hint?: unknown;

Defined in: source/template.ts:799

An optional hint to help apps and users understand this data field.

type

type: XOTemplatePrimitiveType;

Defined in: source/template.ts:789

The data type of this data field.

value

value: unknown;

Defined in: source/template.ts:794

The value for this data field.

XOTemplateDataIdentifier

type XOTemplateDataIdentifier = string;

Defined in: source/template.ts:131

Identifies a data field defined in the template's data.

XOTemplateDefaults

type XOTemplateDefaults = object;

Defined in: source/template.ts:841

Default settings applied across the template when no explicit per-action overrides are given.

Properties

address?

optional address?: XOTemplateLockingScriptIntent;

Defined in: source/template.ts:851

Configure the default intent structure for creating receiving addresses / locking scripts.

change?

optional change?: XOTemplateOutputIntent;

Defined in: source/template.ts:846

Instructions for how to construct automated change output.

receive?

optional receive?: XOTemplateOutputIntent;

Defined in: source/template.ts:856

Configure the default intent structure for creating receive outputs.

XOTemplateIcon

type XOTemplateIcon = object;

Defined in: source/template.ts:809

An icon reference in the template.

Properties

hash

hash: string;

Defined in: source/template.ts:819

The identifier of the icon.

name

name: string;

Defined in: source/template.ts:814

A name for this icon.

XOTemplateIdentifier

type XOTemplateIdentifier = string;

Defined in: source/template.ts:137

Identifier for an XO template.

XOTemplateImportDefaultValue

type XOTemplateImportDefaultValue = XOTemplateIntent & Partial<XOTemplateViewProperties>;

Defined in: source/template.ts:754

An import default value intent. Extends the base intent with optional view properties that the engine evaluates at runtime to produce human-readable output. The engine overrides whatever values are set here when resolving the target for a participant.

XOTemplateInput

type XOTemplateInput = XOTemplateViewProperties & object;

Defined in: source/template.ts:572

An input definition in the template.

Type Declaration

Name	Type	Description	Defined in
`omitChangeAmounts?`	`XOTemplateAssetAmounts`	Amount of change that should be omitted from the automatic change handling. WARNING: Setting this can result in loss of funds!	source/template.ts:601
`sequenceNumber?`	`number` \| `string`	The sequence number of this input. - `number`: A specific sequence number. - `string`: A CashASM expression that resolves to the sequence number.	source/template.ts:591
`token?`	`XOTemplateToken` \| `null`	Token configuration for this input.	source/template.ts:584
`unlockingScript?`	`string`	Identifier of the unlocking script to use for the UTXO provided for this input.	source/template.ts:596
`valueSatoshis?`	`Satoshis` \| `string`	The amount of satoshis for this input. - `Satoshis`: A specific amount of satoshis. - `string`: A CashASM expression that resolves to the satoshi amount.	source/template.ts:579

XOTemplateInputIdentifier

type XOTemplateInputIdentifier = string;

Defined in: source/template.ts:110

Identifies an input defined in the template's inputs.

XOTemplateIntent

type XOTemplateIntent = object;

Defined in: source/template.ts:173

The base intent structure. Describes the common data parameters shared by all intent types regardless of what they target. An optional templateIdentifier allows the intent to reference a target defined in a different template.

Properties

constants?

optional constants?: Record<XOTemplateConstantIdentifier, unknown>[];

Defined in: source/template.ts:193

Constant values to apply when this intent is resolved.

generate?

optional generate?: string[];

Defined in: source/template.ts:183

Identifiers for items to generate when this intent is resolved (e.g. keys or secrets).

role?

optional role?: XOTemplateRoleIdentifier;

Defined in: source/template.ts:203

Optional identifier for the role used in this intent.

secrets?

optional secrets?: Record<XOTemplateSecretIdentifier, unknown>[];

Defined in: source/template.ts:198

Secret values to apply when this intent is resolved.

templateIdentifier?

optional templateIdentifier?: XOTemplateIdentifier;

Defined in: source/template.ts:178

Optional identifier for the template used in this intent. If not provided, uses the current template.

variables?

optional variables?: Record<XOTemplateVariableIdentifier, unknown>[];

Defined in: source/template.ts:188

Variable values to apply when this intent is resolved.

XOTemplateLockingScript

type XOTemplateLockingScript = XOTemplateViewProperties & object;

Defined in: source/template.ts:515

A locking script definition in the template.

Type Declaration

Name	Type	Description	Defined in
`actions?`	`XOTemplateActionIntent`[]	The actions available for this locking script.	source/template.ts:535
`balance?`	`Partial`<`XOTemplateAssetAmounts`>	Estimated ownership in the optional set of asset amounts specified.	source/template.ts:545
`lockingBytecode`	`string`	The locking script bytecode.	source/template.ts:525
`lockingType?`	`XOTemplateLockingType`	The type of locking mechanism. Defaults to 'p2s' if not specified.	source/template.ts:520
`privacy?`	`number` \| `string`	Privacy level for outputs locked to this script. - `number`: A numeric privacy level. - `string`: A CashASM expression that evaluates to a privacy level.	source/template.ts:557
`roles?`	`Record`<`XOTemplateRoleIdentifier`, `XOTemplateLockingScriptRole`>	Specific context for each role participating in this locking script.	source/template.ts:562
`selectable?`	`boolean`	Whether outputs locked to this script should be available for coin selection.	source/template.ts:550
`state?`	`XOTemplateState`	List of items to track as state for all participants.	source/template.ts:540
`unlockingBytecode?`	`string`	Optional default unlocking bytecode when used in automatic coin selection.	source/template.ts:530

XOTemplateLockingScriptIdentifier

type XOTemplateLockingScriptIdentifier = string;

Defined in: source/template.ts:116

Identifies a locking script defined in the template's lockingScripts.

XOTemplateLockingScriptIntent

type XOTemplateLockingScriptIntent = XOTemplateIntent & object;

Defined in: source/template.ts:231

An intent that targets a specific locking script.

Type Declaration

Name	Type	Description	Defined in
`lockingScript`	`XOTemplateLockingScriptIdentifier`	The identifier for the intended locking script.	source/template.ts:236

XOTemplateLockingScriptRole

type XOTemplateLockingScriptRole = Partial<XOTemplateViewProperties> & object;

Defined in: source/template.ts:473

A role definition within a locking script.

Type Declaration

Name	Type	Description	Defined in
`actions?`	`XOTemplateActionIntent`[]	List of action references available to this role.	source/template.ts:483
`balance?`	`Partial`<`XOTemplateAssetAmounts`>	Estimated ownership in the optional set of asset amounts specified.	source/template.ts:488
`privacy?`	`number` \| `string`	Privacy level for outputs locked to this script. - `number`: A numeric privacy level. - `string`: A CashASM expression that evaluates to a privacy level.	source/template.ts:509
`relevant?`	`boolean` \| `string`	Whether this output or locking script should be tracked by the engine. When omitted, the engine treats this field as true. - `true`: Include it. - `false`: Exclude it. - `string`: A CashASM expression that evaluates to a boolean relevance value.	source/template.ts:502
`selectable?`	`boolean`	Whether outputs locked to this script should be available for coin selection.	source/template.ts:493
`state?`	`XOTemplateState`	List of items to track as state for this role.	source/template.ts:478

XOTemplateLockingType

type XOTemplateLockingType = ValueOf<typeof XOTemplateLockingTypes>;

Defined in: source/template.ts:65

The standard locking script types supported by XO.

XOTemplateNftCapability

type XOTemplateNftCapability = ValueOf<typeof XOTemplateNftCapabilities>;

Defined in: source/template.ts:50

The capability of a non-fungible token. minting can create new NFTs of the same category. mutable can update its own commitment data. none means the commitment is immutable.

XOTemplateNonFungibleTokenDetails

type XOTemplateNonFungibleTokenDetails = object;

Defined in: source/template.ts:376

Non-fungible token configuration within a token field.

Properties

capability?

optional capability?: XOTemplateNftCapability | string;

Defined in: source/template.ts:381

The capability of the NFT. May be a known capability value or a CashASM expression resolving to a capability.

commitment?

optional commitment?: string;

Defined in: source/template.ts:386

The commitment data for the NFT, as a string or CashASM expression resolving to a commitment.

XOTemplateOutput

type XOTemplateOutput = Omit<XOTemplateLockingScript, "lockingType" | "lockingBytecode" | "unlockingBytecode"> & object;

Defined in: source/template.ts:614

An output definition in the template. Inherits all fields from XOTemplateLockingScript except lockingType, lockingBytecode and unlockingBytecode: outputs reference a locking script by identifier rather than defining one inline, so repeating any of these fields here would create an ambiguity about which declaration takes precedence.

Type Declaration

Name	Type	Description	Defined in
`lockingScript`	`XOTemplateLockingScriptIdentifier`	Identifier of the locking script to use for this output.	source/template.ts:619
`token?`	`XOTemplateToken` \| `null`	Token configuration for this output.	source/template.ts:631
`valueSatoshis?`	`Satoshis` \| `string`	The amount of satoshis for this output. - `Satoshis`: A specific amount of satoshis. - `string`: A CashASM expression that resolves to the satoshi amount.	source/template.ts:626

XOTemplateOutputIdentifier

type XOTemplateOutputIdentifier = string;

Defined in: source/template.ts:113

Identifies an output defined in the template's outputs.

XOTemplateOutputIntent

type XOTemplateOutputIntent = XOTemplateIntent & object;

Defined in: source/template.ts:220

An intent that targets a specific output.

Type Declaration

Name	Type	Description	Defined in
`output`	`XOTemplateOutputIdentifier`	The identifier for the intended output.	source/template.ts:225

XOTemplatePrimitiveType

type XOTemplatePrimitiveType = ValueOf<typeof XOTemplatePrimitiveTypes>;

Defined in: source/template.ts:97

The primitive types that can be declared in an XO template. Used by constants, variables, and data fields.

XOTemplateResource

type XOTemplateResource = XOTemplateViewProperties & object;

Defined in: source/template.ts:826

A resource reference attached to a template. Extends view properties with a URL pointing to external documentation or tooling.

Type Declaration

Name	Type	Description	Defined in
`url`	`string`	The URL for this resource.	source/template.ts:831

XOTemplateRoleIdentifier

type XOTemplateRoleIdentifier = string;

Defined in: source/template.ts:104

Identifies a role defined in the template's roles.

XOTemplateRoleSlot

type XOTemplateRoleSlot = object;

Defined in: source/template.ts:298

A role entry in an action's requirements block. Declares which role must participate and how many slots are needed.

Properties

role

role: XOTemplateRoleIdentifier;

Defined in: source/template.ts:303

The role identifier that this requirement applies to.

slots

slots: XOTemplateRoleSlotsRequirements;

Defined in: source/template.ts:308

Slot configuration specifying how many participants of this role are required.

XOTemplateRoleSlotsRequirements

type XOTemplateRoleSlotsRequirements = object;

Defined in: source/template.ts:281

Slot configuration for a role. Declares how many participants of a given role are needed to satisfy the action's requirements.

Properties

max?

optional max?: number;

Defined in: source/template.ts:291

Maximum number of participants allowed for this role. Undefined means unlimited.

min

min: number;

Defined in: source/template.ts:286

Minimum number of participants required for this role.

XOTemplateScriptIdentifier

type XOTemplateScriptIdentifier = string;

Defined in: source/template.ts:119

Identifies a script defined in the template's scripts.

XOTemplateSecretIdentifier

type XOTemplateSecretIdentifier = string;

Defined in: source/template.ts:134

Identifies a secret defined in a role or action's secrets list.

XOTemplateState

type XOTemplateState = object;

Defined in: source/template.ts:453

State configuration shared by a locking script and its individual roles. Declares which variables and secrets are tracked in the on-chain state for that participant.

Properties

secrets?

optional secrets?: XOTemplateSecretIdentifier[];

Defined in: source/template.ts:463

List of secret identifiers to track in state.

variables?

optional variables?: XOTemplateVariableIdentifier[];

Defined in: source/template.ts:458

List of variable identifiers to track in state.

XOTemplateToken

type XOTemplateToken = object;

Defined in: source/template.ts:392

Token configuration for outputs and inputs.

Properties

amount?

optional amount?: bigint | string | null;

Defined in: source/template.ts:402

The amount of fungible tokens as a bigint, a CashASM expression resolving to a bigint, or null indicating no FT is present.

category?

optional category?: string;

Defined in: source/template.ts:397

The category of the token, as a string or CashASM expression resolving to a category.

nft?

optional nft?: 
  | XOTemplateNonFungibleTokenDetails
  | null;

Defined in: source/template.ts:407

Non-fungible token configuration. Null indicates no NFT is present.

XOTemplateTransaction

type XOTemplateTransaction = XOTemplateViewProperties & object;

Defined in: source/template.ts:689

A transaction template definition.

Type Declaration

Name	Type	Description	Defined in
`composable?`	`boolean`	Whether this transaction can be composed with other transactions.	source/template.ts:721
`inputs`	`XOTemplateTransactionInput`[]	The inputs for this transaction.	source/template.ts:706
`locktime?`	`number` \| `string`	The locktime for this transaction. - `number`: A specific locktime value. - `string`: A CashASM expression that resolves to the locktime.	source/template.ts:701
`outputs`	`XOTemplateTransactionOutput`[]	The outputs for this transaction.	source/template.ts:711
`roles?`	`Record`<`XOTemplateRoleIdentifier`, `XOTemplateTransactionRoleData`>	Specific context for each role participating in this transaction.	source/template.ts:716
`version?`	`number`	The version of the transaction.	source/template.ts:694

XOTemplateTransactionIdentifier

type XOTemplateTransactionIdentifier = string;

Defined in: source/template.ts:122

Identifies a transaction defined in the template's transactions.

XOTemplateTransactionInput

type XOTemplateTransactionInput = object;

Defined in: source/template.ts:641

Reference to an input in a transaction definition in the template.

Properties

input

input: XOTemplateInputIdentifier;

Defined in: source/template.ts:646

The input definition identifier.

inputIndex?

optional inputIndex?: number;

Defined in: source/template.ts:651

Optional index of this input in the transaction.

XOTemplateTransactionOutput

type XOTemplateTransactionOutput = object;

Defined in: source/template.ts:657

Reference to an output in a transaction definition in the template.

Properties

output

output: XOTemplateOutputIdentifier;

Defined in: source/template.ts:662

The output definition identifier.

outputIndex?

optional outputIndex?: number;

Defined in: source/template.ts:667

Optional index of this output in the transaction.

XOTemplateTransactionRoleData

type XOTemplateTransactionRoleData = Partial<XOTemplateViewProperties> & object;

Defined in: source/template.ts:673

Role-specific data for a transaction within a template.

Type Declaration

Name	Type	Description	Defined in
`inputs?`	`XOTemplateTransactionInput`[]	The inputs required for this role.	source/template.ts:678
`outputs?`	`XOTemplateTransactionOutput`[]	The outputs required for this role.	source/template.ts:683

XOTemplateVariable

type XOTemplateVariable = XOTemplateViewProperties & object;

Defined in: source/template.ts:759

A variable definition in the template.

Type Declaration

Name	Type	Description	Defined in
`hint?`	`unknown`	A hint to help users understand what value to provide.	source/template.ts:769
`importDefaultValue?`	`XOTemplateImportDefaultValue`	A neutral intent that the engine uses to populate the default value for this variable. View properties (name, description, icon) may contain CashASM expressions that the engine evaluates at runtime to produce human-readable output.	source/template.ts:776
`type?`	`XOTemplatePrimitiveType`	The data type of this variable.	source/template.ts:764

XOTemplateVariableIdentifier

type XOTemplateVariableIdentifier = string;

Defined in: source/template.ts:125

Identifies a variable defined in the template's variables.

XOTemplateViewProperties

type XOTemplateViewProperties = object;

Defined in: source/template.ts:146

Human-readable display properties shared by most template elements.

Properties

description

description: string;

Defined in: source/template.ts:156

A human-readable explanation of what this element does and when it is relevant.

icon?

optional icon?: string;

Defined in: source/template.ts:161

An optional icon identifier.

name

name: string;

Defined in: source/template.ts:151

A short human-readable label for this element.

BchVmVersions

const BchVmVersions: object;

Defined in: source/template.ts:20

Values for BCH VM versions that an XO template can declare support for.

Type Declaration

Name	Type	Defined in
`BCH_2020_05`	`"BCH_2020_05"`	source/template.ts:20
`BCH_2021_05`	`"BCH_2021_05"`	index.d.mts:36
`BCH_2022_05`	`"BCH_2022_05"`	index.d.mts:37
`BCH_2023_05`	`"BCH_2023_05"`	index.d.mts:38
`BCH_2024_05`	`"BCH_2024_05"`	index.d.mts:39
`BCH_2025_05`	`"BCH_2025_05"`	index.d.mts:40
`BCH_2026_05`	`"BCH_2026_05"`	index.d.mts:41

XOTemplateLockingTypes

const XOTemplateLockingTypes: object;

Defined in: source/template.ts:55

Values for XO template locking script types.

Type Declaration

Name	Type	Defined in
`P2PKH`	`"p2pkh"`	index.d.mts:67
`P2S`	`"p2s"`	source/template.ts:55
`P2SH`	`"p2sh"`	index.d.mts:68

XOTemplateNftCapabilities

const XOTemplateNftCapabilities: object;

Defined in: source/template.ts:38

Values for NFT capability on template token fields.

Type Declaration

Name	Type	Defined in
`MINTING`	`"minting"`	index.d.mts:53
`MUTABLE`	`"mutable"`	index.d.mts:52
`NONE`	`"none"`	source/template.ts:38

XOTemplatePrimitiveTypes

const XOTemplatePrimitiveTypes: object;

Defined in: source/template.ts:71

Values for primitive types declared in an XO template. Used by constants, variables, and data fields.

Type Declaration

Name	Type	Defined in
`BIGINT`	`"bigint"`	index.d.mts:83
`BOOLEAN`	`"boolean"`	source/template.ts:71
`BYTES`	`"bytes"`	index.d.mts:81
`EXTENDED_PUBLIC_KEY`	`"extended_public_key"`	index.d.mts:87
`FUNGIBLE_TOKEN_AMOUNT`	`"token_amount"`	index.d.mts:89
`INTEGER`	`"integer"`	index.d.mts:82
`LOCKING_SCRIPT`	`"locking_script"`	index.d.mts:95
`NFT_COMMITMENT`	`"nft_commitment"`	index.d.mts:94
`NON_FUNGIBLE_TOKEN_CAPABILITY`	`"token_capability"`	index.d.mts:90
`NON_FUNGIBLE_TOKEN_COMMITMENT`	`"token_commitment"`	index.d.mts:91
`PRIVATE_KEY`	`"private_key"`	index.d.mts:85
`PUBLIC_KEY`	`"public_key"`	index.d.mts:86
`SATOSHIS`	`"satoshis"`	index.d.mts:88
`SCHNORR_SIGNATURE`	`"signature"`	index.d.mts:98
`STRING`	`"string"`	index.d.mts:84
`TEMPLATE_IDENTIFIER`	`"template_identifier"`	index.d.mts:97
`TIMESTAMP`	`"timestamp"`	index.d.mts:92
`TOKEN_CATEGORY`	`"token_category"`	index.d.mts:93
`TRANSACTION_HASH`	`"transaction_hash"`	index.d.mts:96

@xo-cash/types ​

Installation ​

Usage ​

Development ​

Formatting ​

Links ​

License ​

BchVmVersion ​

FungibleTokenAmount ​

OutputNft ​

OutputToken ​

Satoshis ​

ValueOf ​

Type Parameters ​

Example ​

XOInvitation ​

Properties ​

actionIdentifier ​

commits ​

createdAtTimestamp ​

invitationIdentifier ​

result? ​

templateIdentifier ​

XOInvitationActionReference ​

Properties ​

actionIdentifier ​

templateIdentifier ​

XOInvitationCommit ​

Properties ​

actionReference? ​

commitIdentifier ​

createdAtTimestamp ​

data ​

entityIdentifier ​

expiresAtTimestamp ​

memo? ​

previousCommitIdentifier ​

signature ​

XOInvitationCommitData ​

Properties ​

inputs? ​

outputs? ​

resolutions? ​

roleIdentifier? ​

transactionLocktime? ​

transactionVersion? ​

variables? ​

XOInvitationCommitDataItemIndex ​

XOInvitationCommitIdentifier ​

XOInvitationDataResult ​

Properties ​

createdAtTimestamp ​

createdByEntityIdentifier ​

createdBySignature ​

value ​

XOInvitationEntityIdentifier ​

XOInvitationIdentifier ​

XOInvitationInput ​

Type Declaration ​

XOInvitationMemo ​

XOInvitationMergesWithReference ​

Properties ​

commitIdentifier ​

itemIndex ​

XOInvitationOutput ​

Type Declaration ​

XOInvitationRequirements ​

Type Declaration ​

XOInvitationResolution ​

Properties ​

resolutionIdentifier ​

roleIdentifier? ​

value ​

XOInvitationResolutionIdentifier ​

XOInvitationResult ​

Properties ​

data? ​

transactions? ​

XOInvitationRoleRequirement ​

XOInvitationSignature ​

@xo-cash/types

Installation

Usage

Development

Formatting

Links

License

BchVmVersion

FungibleTokenAmount

OutputNft

OutputToken

Satoshis

ValueOf

Type Parameters

Example

XOInvitation

Properties

actionIdentifier

commits

createdAtTimestamp

invitationIdentifier

result?

templateIdentifier

XOInvitationActionReference

Properties

actionIdentifier

templateIdentifier

XOInvitationCommit

Properties

actionReference?

commitIdentifier

createdAtTimestamp

data

entityIdentifier

expiresAtTimestamp

memo?

previousCommitIdentifier

signature

XOInvitationCommitData

Properties

inputs?

outputs?

resolutions?

roleIdentifier?

transactionLocktime?

transactionVersion?

variables?

XOInvitationCommitDataItemIndex

XOInvitationCommitIdentifier

XOInvitationDataResult

Properties

createdAtTimestamp

createdByEntityIdentifier

createdBySignature

value

XOInvitationEntityIdentifier

XOInvitationIdentifier

XOInvitationInput

Type Declaration

XOInvitationMemo

XOInvitationMergesWithReference

Properties

commitIdentifier

itemIndex

XOInvitationOutput

Type Declaration

XOInvitationRequirements

Type Declaration

XOInvitationResolution

Properties

resolutionIdentifier

roleIdentifier?

value

XOInvitationResolutionIdentifier

XOInvitationResult

Properties

data?

transactions?

XOInvitationRoleRequirement

XOInvitationSignature