# 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).