equity/README.md

   1 # equity compiler tool
   2
   3 The equity compiler tool is the equity commandline compiler.
   4
   5 ## Requirements
   6
   7 [Go](https://golang.org/doc/install) version 1.8 or higher, with `$GOPATH` set to your preferred directory
   8
   9 Build source code, the build target of the equity compiler commandline tool is `equity`.
  10
  11 ```bash
  12 $ make tool
  13 ```
  14
  15 then change directory to `equity`, and you can find the tool `equity` :
  16 ```bash
  17 $ cd equity
  18 ```
  19
  20 ## Usage on the commandline
  21
  22 Usage of equity commandline compiler:
  23 ```shell
  24 $ ./equity <input_file> [flags]
  25 ```
  26
  27 Using help provides you with an explanation of all options.
  28
  29 ```shell
  30 $ ./equity --help
  31 ```
  32
  33 available flags:
  34 ```shell
  35     --bin        Binary of the contracts in hex.
  36     --instance   Object of the Instantiated contracts.
  37     --shift      Function shift of the contracts.
  38 ```
  39
  40 ## Example
  41
  42 The contents of the contract file `TradeOffer`(without file suffix restrictions) are as follows:
  43 ```js
  44 contract TradeOffer(assetRequested: Asset,
  45                     amountRequested: Amount,
  46                     seller: Program,
  47                     cancelKey: PublicKey) locks valueAmount of valueAsset {
  48   clause trade() {
  49     lock amountRequested of assetRequested with seller
  50     unlock valueAmount of valueAsset
  51   }
  52   clause cancel(sellerSig: Signature) {
  53     verify checkTxSig(cancelKey, sellerSig)
  54     unlock valueAmount of valueAsset
  55   }
  56 }
  57 ```
  58
  59 - Compiler contract file to generate the binary:
  60 ```shell
  61 ./equity TradeOffer --bin
  62 ```
  63
  64   the return result:
  65 ```shell
  66 ======= TradeOffer =======
  67 Binary:
  68 547a6413000000007b7b51547ac1631a000000547a547aae7cac
  69 ```
  70
  71 - Query the clause shift for contract:
  72 ```shell
  73 ./equity TradeOffer --shift
  74 ```
  75
  76   the return result:
  77 ```shell
  78 ======= TradeOffer =======
  79 Clause shift:
  80     trade:  00000000
  81     cancel:  13000000
  82     ending:  1a000000
  83 ```
  84
  85 NOTE:
  86 If the contract contains only one clause, Users don't need clause selector when unlock contract. Furthermore, there is no signification for ending clause shift except for display.
  87
  88 - Instantiated contract with arguments:
  89 ```shell
  90 ./equity TradeOffer --instance 84fe51a7739e8e2fe28e7042bb114fd6d6abd09cd22af867729ea001c87cd550 1000 0014d6598ab7dce6b04d43f31ad6eed76b18da553e94 7975f3f71ca7f55ecdef53ccf44224d514bc584bc065770bba8dcdb9d7f9ae6c
  91 ```
  92
  93   the return result:
  94 ```shell
  95 ======= TradeOffer =======
  96 Instantiated program:
  97 207975f3f71ca7f55ecdef53ccf44224d514bc584bc065770bba8dcdb9d7f9ae6c160014d6598ab7dce6b04d43f31ad6eed76b18da553e9402e8032084fe51a7739e8e2fe28e7042bb114fd6d6abd09cd22af867729ea001c87cd550741a547a6413000000007b7b51547ac1631a000000547a547aae7cac00c0
  98 ```
  99
 100 When you don't know the order of the contract parameters, you can use the prompt function:
 101 ```shell
 102 ./equity TradeOffer --instance
 103 ```
 104
 105   the commandline tips:
 106 ```shell
 107 ======= TradeOffer =======
 108 Instantiated program:
 109 Error: The number of input arguments 0 is less than the number of contract parameters 4
 110 Usage:
 111   equity TradeOffer <assetRequested> <amountRequested> <seller> <cancelKey>
 112 ```
 113
 114 The input contract argument description:
 115
 116 | type | value description |
 117 | ---- | ----------- |
 118 | Boolean | true/1 , false/0 |
 119 | Integer | 0 ~ 2^63-1 |
 120 | Amount | -2^63 ~ 2^63-1 |
 121 | Asset | hex string with length 64 |
 122 | Hash | hex string with length 64 |
 123 | PublicKey | hex string with length 64 |
 124 | Program | hex string |
 125 | String | string with ASCII, e.g., "this is a test string" |