compiler/doc.go

   1 /*
   2 Package equity provides a compiler for Chain'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 Chain 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 May 2017.
  14
  15   program = contract*
  16
  17   contract = "contract" identifier "(" [params] ")" "locks" identifier "{" clause+ "}"
  18
  19     The identifier after "locks" is a name for the value locked by
  20     the contract. It must be unlocked or re-locked (with "unlock"
  21     or "lock") in every clause.
  22
  23   clause = "clause" identifier "(" [params] ")" ["requires" requirements] "{" statement+ "}"
  24
  25     The requirements are blockchain values that must be present in
  26     the spending transaction in order to spend the value locked by
  27     the earlier transaction. Each such value must be re-locked
  28     (with "lock") in its clause.
  29
  30   statement = verify | unlock | lock
  31
  32   verify = "verify" expr
  33
  34     Verifies that boolean expression expr produces a true result.
  35
  36   unlock = "unlock" expr
  37
  38     Expr must evaluate to the contract value. This unlocks that
  39     value for any use.
  40
  41   lock = "lock" expr "with" expr
  42
  43     The first expr must be a blockchain value (i.e., one named
  44     with "locks" or "requires"). The second expr must be a
  45     program. This unlocks expr and re-locks it with the new
  46     program.
  47
  48   requirements = requirement | requirements "," requirement
  49
  50   requirement = identifier ":" expr "of" expr
  51
  52     The first expr must be an amount, the second must be an
  53     asset. This denotes that the named value must have the given
  54     quantity and asset type.
  55
  56   params = param | params "," param
  57
  58   param = idlist ":" identifier
  59
  60     The identifiers in idlist are individual parameter names. The
  61     identifier after the colon is their type. Available types are:
  62
  63       Amount; Asset; Boolean; Hash; Integer; Program; PublicKey;
  64       Signature; String; Time
  65
  66   idlist = identifier | idlist "," identifier
  67
  68   expr = unary_expr | binary_expr | call_expr | identifier | "(" expr ")" | literal
  69
  70   unary_expr = unary_op expr
  71
  72   binary_expr = expr binary_op expr
  73
  74   call_expr = expr "(" [args] ")"
  75
  76     If expr is the name of an Equity contract, then calling it (with
  77     the appropriate arguments) produces a program suitable for use
  78     in "lock" statements.
  79
  80     Otherwise, expr should be one of these builtin functions:
  81
  82       sha3(x)
  83         SHA3-256 hash of x.
  84       sha256(x)
  85         SHA-256 hash of x.
  86       size(x)
  87         Size in bytes of x.
  88       abs(x)
  89         Absolute value of x.
  90       min(x, y)
  91         The lesser of x and y.
  92       max(x, y)
  93         The greater of x and y.
  94       checkTxSig(pubkey, signature)
  95         Whether signature matches both the spending
  96         transaction and pubkey.
  97       concat(x, y)
  98         The concatenation of x and y.
  99       concatpush(x, y)
 100         The concatenation of x with the bytecode sequence
 101         needed to push y on the ChainVM stack.
 102       before(x)
 103         Whether the spending transaction is happening before
 104         time x.
 105       after(x)
 106         Whether the spending transaction is happening after
 107         time x.
 108       checkTxMultiSig([pubkey1, pubkey2, ...], [sig1, sig2, ...])
 109         Like checkTxSig, but for M-of-N signature checks.
 110         Every sig must match both the spending transaction and
 111         one of the pubkeys. There may be more pubkeys than
 112         sigs, but they are only checked left-to-right so must
 113         be supplied in the same order as the sigs. The square
 114         brackets here are literal and must appear as shown.
 115
 116   unary_op = "-" | "~"
 117
 118   binary_op = ">" | "<" | ">=" | "<=" | "==" | "!=" | "^" | "|" |
 119         "+" | "-" | "&" | "<<" | ">>" | "%" | "*" | "/"
 120
 121   args = expr | args "," expr
 122
 123   literal = int_literal | str_literal | hex_literal
 124
 125 */
 126 package compiler