equity/compiler/doc.go

   1 /*
   2 Package equity provides a compiler for Bytom's Equity contract language.
   3
   4 A contract is a means to lock some payment in the output of a
   5 transaction. It contains a number of clauses, each describing a way to
   6 unlock, or redeem, the payment in a subsequent transaction.  By
   7 executing the statements in a clause, using contract arguments
   8 supplied by the payer and clause arguments supplied by the redeemer,
   9 nodes in a Bytom network can determine whether a proposed spend is
  10 valid.
  11
  12 The language definition is in flux, but here's what's implemented as
  13 of late Nov 2018.
  14
  15   program = contract*
  16
  17   contract = "contract" identifier "(" [params] ")" "locks" amount_identifier of asset_identifier "{" clause+ "}"
  18
  19     The value(amount_identifier of asset_identifier) after "locks" is a name for
  20     the value locked by the contract. It must be unlocked or re-locked (with "unlock"
  21     or "lock") in every clause.
  22
  23   clause = "clause" identifier "(" [params] ")" "{" statement+ "}"
  24
  25   statement = verify | unlock | lock | define | assign | if/else
  26
  27   verify = "verify" expr
  28
  29     Verifies that boolean expression expr produces a true result.
  30
  31   unlock = "unlock" expr "of" expr
  32
  33     The first expr must be an amount, the second must be an asset.
  34     the value(expr "of" expr) must evaluate to the contract value.
  35     This unlocks that value for any use.
  36
  37   lock = "lock" expr "of" expr "with" expr
  38
  39     The first expr must be an amount, the second must be an asset.
  40     The later expr after "with" must be a program. This expression describe that
  41     the value(expr "of" expr) is unlocked and re-locks it with the new program immediately.
  42
  43   define = "define" identifier : TypeName ["=" expr]
  44
  45     Define a temporary variable "identifier" with type "TypeName". the identifier can be defined only
  46     or assigned with expr.
  47
  48   assign = "assign" identifier "=" expr
  49
  50     Assign a temporary variable "identifier" with expr. Please note that
  51     the "identifier" must be the defined variable with "define" expression.
  52
  53   if = "if" expr "{" statement+ "}" [else "{" statement+ "}"]
  54
  55     The check condition after "if" must be boolean expression. The if-else executes the statements
  56     inside the body of if-statement when condition expression is true, otherwise executes the statements
  57     inside the body of else-statement.
  58
  59   params = param | params "," param
  60
  61   param = identifier ":" type
  62
  63     The identifier are individual parameter name. The identifier after the colon is their type.
  64     Available types are:
  65
  66       Amount; Asset; Boolean; Hash; Integer; Program;
  67       PublicKey; Signature; String
  68
  69   idlist = identifier | idlist "," identifier
  70
  71   expr = unary_expr | binary_expr | call_expr | identifier | "(" expr ")" | literal
  72
  73   unary_expr = unary_op expr
  74
  75   binary_expr = expr binary_op expr
  76
  77   call_expr = expr "(" [args] ")"
  78
  79     If expr is the name of an Equity contract, then calling it (with
  80     the appropriate arguments) produces a program suitable for use
  81     in "lock" statements.
  82
  83     Otherwise, expr should be one of these builtin functions:
  84
  85       sha3(x)
  86         SHA3-256 hash of x.
  87       sha256(x)
  88         SHA-256 hash of x.
  89       size(x)
  90         Size in bytes of x.
  91       abs(x)
  92         Absolute value of x.
  93       min(x, y)
  94         The lesser of x and y.
  95       max(x, y)
  96         The greater of x and y.
  97       checkTxSig(pubkey, signature)
  98         Whether signature matches both the spending
  99         transaction and pubkey.
 100       concat(x, y)
 101         The concatenation of x and y.
 102       concatpush(x, y)
 103         The concatenation of x with the bytecode sequence
 104         needed to push y on the BVM stack.
 105       below(x)
 106         Whether the spending transaction is happening before
 107         blockHeight x.
 108       above(x)
 109         Whether the spending transaction is happening after
 110         blockHeight x.
 111       checkTxMultiSig([pubkey1, pubkey2, ...], [sig1, sig2, ...])
 112         Like checkTxSig, but for M-of-N signature checks.
 113         Every sig must match both the spending transaction and
 114         one of the pubkeys. There may be more pubkeys than
 115         sigs, but they are only checked left-to-right so must
 116         be supplied in the same order as the sigs. The square
 117         brackets here are literal and must appear as shown.
 118
 119   unary_op = "-" | "~"
 120
 121   binary_op = ">" | "<" | ">=" | "<=" | "==" | "!=" | "^" | "|" |
 122         "+" | "-" | "&" | "<<" | ">>" | "%" | "*" | "/"
 123
 124   args = expr | args "," expr
 125
 126   literal = int_literal | str_literal | hex_literal
 127
 128 */
 129 package compiler