Simulation pseudo-commands

Syntax:

type:label = variable, where type may be 
	* string, UTF-8 which must be double-quoted if contains whitespace
	* hex, /^(0x)?[a-fA-F0-9].*$/
	* int, /^\d+$/
| = or
<> = required
[] = optional
-> = return

Ids are strings. Uuid strings are preferred.

State change commands

The command processor MUST ensure that all ids are unique.

If - is supplied as id, a unique, random (uuid4) id MUST be generated. All commands return the (given or generated) id.

All state change commands must implement a success or fail state, that may be used for the control commands (see below).

Further execution MUST aborted and exception MUST be raised if:

• Actions depending on other created assets (keys, vouchers) that have failed to execute
• A store cannot handle a command (e.g. the custodial store may not handle voucher creation)

Create a new key

KEY_CREATE <id | "-"> <string:key_name> <string:store_name> [hex:private_key] -> id

The initial use-case for the store is to choose between custodial system and independent keystore (simulating sovereign key holders). Future use-cases may need to use other stores aswell (e.g. a HTTP service that stores keystore files for given private keys).

The key_name or the returned address may be used to refer to the key after the command is executed.

Further execution MUST aborted and exception MUST be raised if private key is given and the store cannot store provided private keys.

Create a new voucher

VOUCHER_CREATE <id | "-"> <string:voucher_symbol> <string:voucher_name> <int:decimals> [<int:decay_factor> <int:decay_period> [hex:sink_address]] -> id

Voucher create MUST guarantee unique token symbol. If the requested symbol is already in use, the processor SHOULD try to append random ascii data to the symbol and try again until success.

The "decay" parameters specify that a contract with demurrage features must be used. If sink_address is not set, it defaults to the burn address (0x000000000000000000000000000000000000dEaD).

The voucher_symbol or the returned address may be used to refer to the key after the command is executed.

The command processor SHOULD store the executing key as the "owner" of the voucher.

Mint vouchers

VOUCHER_MINT <id | "-"> <string:voucher_symbol | hex:voucher_address> <int:amount> [<to_account | to_key_name>] -> id

If to_* is not specified, the recipient should be the owner of the voucher.

Transfer vouchers

VOUCHER_TRANSFER <id | "-"> <voucher_symbol | voucher_address> <amount> <to_account | to_key_name> <from_account | from_key_name > id

Control commands

Blocks execution of selected previous commands before continuing.

If value is - will wait for all previous commands since last control command, or since start of script if no previous control command exists.

Unconditional wait

WAIT <id | ->

Continue after execution, regardless of result.

Conditional wait

NEED <id | ->

Continue after execution, but raise exception and abort execution if any of the commands fail.

Report commands

In the event that an interactive tool would be implemented for the protocol, some assistance for puny humans would be required aswell.

PEEK <id>

Return human-readable version of the issued command, its current state, and its associated data (e.g. wallet address, contract address).