Initial commit

README.md

@@ -0,0 +1,84 @@
+# 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 will be generated.
+
+All state change commands must implement a success or fail state, that may be used for the control commands (see below).
+
+Actions depending on other created assets (keys, vouchers) that have failed to execution **MUST** abort further execution and raise exception.
+
+
+### Create a new key
+
+`KEY_CREATE <id | "-"> <string:key_name> <string:store_name> -> hex:wallet_address`
+
+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.
+
+The `key_name` or the returned `address` may be used to refer to the key after the command is executed.
+
+
+### Create a new voucher
+
+`VOUCHER_CREATE <id | "-"> <string:voucher_symbol> <string:voucher_name> <int:decimals> [<int:decay_factor> <int:decay_period> [hex:sink_address]] -> hex:contract_address`
+
+Voucher create **MUST** guarantee unique token symbol. The processor **SHOULD** 
+	-> e.g. if collision, append "_<2 bytes hex rand>"
+
+
+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>] -> hex:to_account`
+
+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 > -> hex:from_account`
+
+
+## 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.