github.com/Bytom/bytom@v1.1.2-0.20210127130405-ae40204c0b09/equity/compiler/doc.go (about)

     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