97 lines
3.4 KiB
Markdown
97 lines
3.4 KiB
Markdown
# 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).
|