Type alias WalletTemplateScenario

Type declaration

• Optional data?: WalletTemplateScenarioData

  An object defining the data to use while compiling this scenario. The properties specified here are used to extend the existing scenario data based on this scenario's extends property.

  Each property is extended individually – to unset a previously-set property, the property must be individually overridden in this object.

• Optional description?: string

  An optionally multi-line, free-form, human-readable description for this scenario (for use in user interfaces). If displayed, this description should use a monospace font to properly render ASCII diagrams.

• Optional extends?: string

  The identifier of the scenario that this scenario extends. Any data or transaction properties not defined in this scenario inherit from the extended parent scenario.

  If undefined, this scenario is assumed to extend the default scenario:

  • The default values for data are set:

    • The identifiers of all Key variables and entities in this template are lexicographically sorted, then each is assigned an incrementing positive integer – beginning with 1 – encoded as an unsigned, 256-bit, big-endian integer (i.e. 0x0000...0001 (32 bytes), 0x0000...0002, 0x0000...0003, etc.). For Keys, this assigned value is used as the private key; For entities, the assigned value is used as the master seed of that entity's HdPrivateKey. If hdKey is set, the addressIndex is set to 0.
    • currentBlockHeight is set to 2. This is the height of the second mined block after the genesis block: 000000006a625f06636b8bb6ac7b960a8d03705d1ace08b1a19da3fdcc99ddbd. This default value was chosen to be low enough to simplify the debugging of block height offsets while remaining differentiated from 0 and 1, which are used both as boolean return values and for control flow.
    • currentBlockTime is set to 1231469665. This is the Median Time-Past block time (BIP113) of block 2.

  • Then transaction is set based on use:

    • if the scenario is being used for transaction estimation, all transaction properties are taken from the transaction being estimated.
    • if the scenario is being used for script testing and validation, the default value for each transaction property is used.

  When a scenario is extended, each property of data and transaction is extended individually: if the extending scenario does not provide a new value for data.bytecode.value or transaction.property, the parent value is used. To avoid inheriting a parent value, each child value must be individually overridden.

• Optional name?: string

  A single-line, Title Case, human-readable name for this scenario for use in user interfaces, e.g.: Delayed Recovery.

• Optional sourceOutputs?: WalletTemplateScenarioSourceOutput[]

  The list of source outputs (a.k.a. UTXOs) to use when generating the compilation context for this scenario.

  The sourceOutputs property must have the same length as transaction.inputs, and each source output must be ordered to match the index of the input that spends it.

  To be valid the sourceOutputs property must have exactly one source output with lockingBytecode set to ["slot"] – the output at the same index as the ["slot"] input in transaction.inputs.

  If undefined, defaults to [{ "lockingBytecode": ["slot"] }].

• Optional transaction?: {
      inputs?: WalletTemplateScenarioInput[];
      locktime?: number;
      outputs?: WalletTemplateScenarioTransactionOutput[];
      version?: number;
  }

  The transaction within which this scenario should be evaluated. This is used for script testing and validation.

  If undefined, inherits the default value for each property:

  {
    "inputs": [{ "unlockingBytecode": ['slot'] }],
    "locktime": 0,
    "outputs": [{ "lockingBytecode": {} }],
    "version": 2
  }
  Copy

  Any transaction property that is not set will be inherited from the scenario specified by extends. when specifying the inputs and outputs properties, each input and output extends the default values for inputs and outputs, respectively.

  For example, an input of {} is interpreted as:

  {
    "outpointIndex": 0,
    "outpointTransactionHash":
      "0000000000000000000000000000000000000000000000000000000000000000",
    "sequenceNumber": 0,
    "unlockingBytecode": ['slot']
  }
  Copy

  And an output of {} is interpreted as:

  {
    "lockingBytecode": {
      "script": ['copy'],
      "overrides": { "hdKeys": { "addressIndex": 1 } }
    },
    "valueSatoshis": 0
  }
  Copy

  • Optional inputs?: WalletTemplateScenarioInput[]

    The list of inputs to use when generating the transaction for this scenario.

    To be valid the inputs property must have exactly one input with unlockingBytecode set to ["slot"]. This is the input in which the unlocking script under test will be placed.

    If undefined, inherits the default scenario inputs value: [{ "unlockingBytecode": ["slot"] }].

  • Optional locktime?: number

    The locktime to use when generating the transaction for this scenario. A positive integer from 0 to a maximum of 4294967295 – if undefined, defaults to 0.

    Locktime can be provided as either a timestamp or a block height. Values less than 500000000 are understood to be a block height (the current block number in the chain, beginning from block 0). Values greater than or equal to 500000000 are understood to be a UNIX timestamp.

    For validating timestamp values, the median timestamp of the last 11 blocks (Median Time-Past) is used. The precise behavior is defined in BIP113.

    If the sequenceNumber of every transaction input is set to 0xffffffff (4294967295), locktime is disabled, and the transaction may be added to a block even if the specified locktime has not yet been reached. When locktime is disabled, if an OP_CHECKLOCKTIMEVERIFY operation is encountered during the verification of any input, an error is produced, and the transaction is invalid.

    Remarks

    There is a subtle difference in how locktime is disabled for a transaction and how it is "disabled" for a single input: locktime is only disabled for a transaction if every input has a sequence number of 0xffffffff; however, within each input, if the sequence number is set to 0xffffffff, locktime is disabled for that input (and OP_CHECKLOCKTIMEVERIFY operations will error if encountered).

    This difference is a minor virtual machine optimization – it allows inputs to be properly validated without requiring the virtual machine to check the sequence number of every other input (only that of the current input).

    This is inconsequential for valid transactions, since any transaction that disables locktime must have disabled locktime for all of its inputs; OP_CHECKLOCKTIMEVERIFY is always properly enforced. However, because an input can individually "disable locktime" without the full transaction actually disabling locktime, it is possible that a carefully-crafted transaction may fail to verify because "locktime is disabled" for the input – even if locktime is actually enforced on the transaction level.

  • Optional outputs?: WalletTemplateScenarioTransactionOutput[]

    The list of outputs to use when generating the transaction for this scenario.

    If undefined, defaults to [{ "lockingBytecode": {} }].

  • Optional version?: number

    The version to use when generating the transaction for this scenario. A positive integer from 0 to a maximum of 4294967295 – if undefined, inherits the default scenario version value: 2.