Version bump and start changelog for 3.5.0 (kadena-io#765)

* Version bump and start changelog for 3.5.0 * regenerate docs * Update docs...creationTime is no longer required * Add documentation for signing commands * Regen docs * Fill out 3.5.0 changelog entries * Update versions in conf.py * One more changelog update * Revert conf.py changes in ja and ko * Fix required status for creationTime in PublicMeta Co-authored-by: Emily Pillmore <[email protected]>
mengby · Jan 29, 2020 · 100365b · 100365b
1 parent b7fce86
commit 100365b
Show file tree

Hide file tree

Showing 7 changed files with 277 additions and 12 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,14 @@
+3.5.0
+---
+
+* Add the commands `sign`, `add-sig`, and `combine-sigs` for working with signatures (#759)
+* Decode StackFrame in JSON output (#755)
+* CommandResult golden coverage (#754)
+* Use CFFI for aeson (upstreamed from chainweb) (#749)
+* Add gas logs to eval result (#748)
+* Add missing case in Eval (#764)
+* Misc updates to docs
+
 3.4.0
 ---
 

diff --git a/docs/en/conf.py b/docs/en/conf.py
@@ -61,9 +61,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = u'3.2'
+version = u'3.5'
 # The full version, including alpha/beta/rc tags.
-release = u'3.2.1'
+release = u'3.5.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -289,7 +289,7 @@
 #
 # latex_appendices = []
 
-# It false, will not define \strong, \code, 	itleref, \crossref ... but only
+# It false, will not define \strong, \code,     itleref, \crossref ... but only
 # \sphinxstrong, ..., \sphinxtitleref, ... To help avoid clash with user added
 # packages.
 #

diff --git a/docs/en/pact-functions.md b/docs/en/pact-functions.md
@@ -393,7 +393,7 @@ Return ID if called during current pact execution, failing if not.
 Obtain current pact build version.
 ```lisp
 pact> (pact-version)
-"3.4.0"
+"3.5.0"
 ```
 
 Top level only: this function will fail if used in module code.

diff --git a/docs/en/pact-functions.rst b/docs/en/pact-functions.rst
@@ -437,7 +437,7 @@ Obtain current pact build version.
 .. code:: lisp
 
    pact> (pact-version)
-   "3.3.1"
+   "3.5.0"
 
 Top level only: this function will fail if used in module code.
 

diff --git a/docs/en/pact-reference.md b/docs/en/pact-reference.md
@@ -965,7 +965,7 @@ The execution request yaml for a public blockchain takes the following keys:
     gasLimit: integer gas limit
     gasPrice: decimal gas price
     ttl: integer time-to-live value
-    creationTime: integer tx execution time after offset
+    creationTime: optional integer tx execution time after offset
   type: exec
 ```
 
@@ -992,13 +992,137 @@ The continuation request yaml for a public blockchain takes the following keys:
     gasLimit: integer gas limit
     gasPrice: decimal gas price
     ttl: integer time-to-live value
-    creationTime: integer tx execution time after offset
+    creationTime: optional integer tx execution time after offset
   nonce: optional request nonce, will use current time if not provided
   type: cont
 ```
 
 Note that the optional "proof" field only makes sense when using cross-chain continuations.
 
+Signing Transactions
+---
+
+As of Pact 3.5.0, the `pact` command line tool now has several commands to
+facilitate signing transactions. Here's a full script showing how these commands
+can be used to prepare an unsigned version of the transaction and add signatures
+to it. This transcript assumes that the details of the transaction has been
+specified in a file called `tx.yaml`.
+
+```
+# At some earlier time generate and save some public/private key pairs.
+pact -g > alice-key.yaml
+pact -g > bob-key.yaml
+
+# Convert a transaction into an unsigned prepared form that is signatures can be added to
+pact -u tx.yaml > tx-unsigned.yaml
+
+# Sign the prepared transaction with one or more keys
+cat tx-unsigned.yaml | pact add-sig alice-key.yaml > tx-signed-alice.yaml
+cat tx-unsigned.yaml | pact add-sig bob-key.yaml > tx-signed-bob.yaml
+
+# Combine the signatures into a fully signed transaction ready to send to the blockchain
+pact combine-sigs tx-signed-alice.yaml tx-signed-bob.yaml > tx-final.json
+
+```
+
+The `add-sig` command takes the output of `pact -u` on standard input and one or
+more key files as command line arguments. It adds the appropriate signatures to
+to the transaction and prints the result to stdout.
+
+The `combine-sigs` command takes multiple unsigned (from `pact -u`) and signed
+(from `pact add-sig`) transaction files as command line arguments and outputs
+the command and all the signatures on stdout.
+
+Both `add-sig` and `combine-sigs` will output YAML if the output transaction
+hasn't accumulated enough signatures to be valid. If all the necessary
+signatures are present, then they will output JSON in final form that is ready
+to be sent to the blockchain on the [`/send` endpoint](#send). If you would like
+to do a test run of the transaction, you can use the `-l` flag to generate
+output suitable for use with the [`/local` endpoint](#local).
+
+The above example adds signatures in parallel, but the `add-sig` command can
+also be used to add signatures sequentially in separate steps or all at once in
+a single step as shown in the following two examples:
+
+```
+cat tx-unsigned.yaml | pact add-sig alice-key.yaml | pact add-sig bob-key.yaml
+cat tx-unsigned.yaml | pact add-sig alice-key.yaml add-sig bob-key.yaml
+```
+
+### Offline Signing with a Cold Wallet
+
+Some cold wallet signing procedures use QR codes to get transaction data on and
+off the cold wallet machine. Since QR codes can transmit a fairly limited amount
+of information these signing commands are also designed to work with a more
+compact data format that doesn't require the full command to generate
+signatures. Here's an example of what `tx-unsigned.yaml` might look like in the
+above example:
+
+```
+hash: KY6RFunty4WazQiCsKsYD-ovu-_XQByfY6scTxi9gQQ
+sigs:
+  368820f80c324bbc7c2b0610688a7da43e39f91d118732671cd9c7500ff43cca: null
+  6be2f485a7af75fedb4b7f153a903f7e6000ca4aa501179c91a2450b777bd2a7: null
+cmd: '{"networkId":"mainnet01","payload":{"exec":{"data":{"ks":{"pred":"keys-all","keys":["368820f80c324bbc7c2b0610688a7da43e39f91d118732671cd9c7500ff43cca"]}},"code":"(coin.transfer-create \"alice\" \"bob\" (read-keyset \"ks\") 100.1)\n(coin.transfer \"bob\" \"alice\" 0.1)"}},"signers":[{"pubKey":"6be2f485a7af75fedb4b7f153a903f7e6000ca4aa501179c91a2450b777bd2a7","clist":[{"args":["alice","bob",100.1],"name":"coin.TRANSFER"},{"args":[],"name":"coin.GAS"}]},{"pubKey":"368820f80c324bbc7c2b0610688a7da43e39f91d118732671cd9c7500ff43cca","clist":[{"args":["bob","alice",0.1],"name":"coin.TRANSFER"}]}],"meta":{"creationTime":1580316382,"ttl":7200,"gasLimit":1200,"chainId":"0","gasPrice":1.0e-5,"sender":"alice"},"nonce":"2020-01-29 16:46:22.916695 UTC"}'
+```
+
+To get a condensed version for signing on a cold wallet all you have to do is
+drop the `cmd` field. This can be done manually or scripted with `cat
+tx-unsigned.yaml | grep -v "^cmd:"`. The result would look like this:
+
+```
+hash: KY6RFunty4WazQiCsKsYD-ovu-_XQByfY6scTxi9gQQ
+sigs:
+  368820f80c324bbc7c2b0610688a7da43e39f91d118732671cd9c7500ff43cca: null
+  6be2f485a7af75fedb4b7f153a903f7e6000ca4aa501179c91a2450b777bd2a7: null
+```
+
+Keep in mind that when you sign these condensed versions, you won't be able to
+submit the output directly to the blockchain. You'll have to use `combine-sigs`
+to combine those signatures with the original `tx-unsigned.yaml` file which has
+the full command.
+
+### Detached Signature Transaction Format
+
+The YAML input expected by `pact -u` is similar to the [Public Blockchain YAML
+format](#request-yaml-public-chain) described above with one major difference.
+Instead of the `keyPairs` field which requires both the public and secret keys,
+`pact -u` expects a `signers` field that only needs a public key. This allows
+signatures to be added on incrementally as described above without needing
+private keys to all be present when the transaction is constructed.
+
+Here is an example of how the above `tx.yaml` file might look:
+
+```
+code: |-
+  (coin.transfer-create "alice" "bob" (read-keyset "ks") 100.1)
+  (coin.transfer "bob" "alice" 0.1)
+data:
+  ks:
+    keys: [368820f80c324bbc7c2b0610688a7da43e39f91d118732671cd9c7500ff43cca]
+    pred: "keys-all"
+publicMeta:
+  chainId: "0"
+  sender: alice
+  gasLimit: 1200
+  gasPrice: 0.0000000001
+  ttl: 7200
+networkId: "mainnet01"
+signers:
+  - public: 6be2f485a7af75fedb4b7f153a903f7e6000ca4aa501179c91a2450b777bd2a7
+    caps:
+      - name: "coin.TRANSFER"
+        args: ["alice", "bob", 100.1]
+      - name: "coin.GAS"
+        args: []
+  - public: 368820f80c324bbc7c2b0610688a7da43e39f91d118732671cd9c7500ff43cca
+    caps:
+      - name: "coin.TRANSFER"
+        args: ["bob", "alice", 0.1]
+type: exec
+```
+
+
 Concepts {#concepts}
 ========
 
@@ -1947,7 +2071,7 @@ Additionally, interfaces my make use of module declarations, admitting use of th
 (interface my-interface
     (defun hello-number:string (number:integer)
       @doc "Return the string \"Hello, $number!\" when given a string"
-      	)
+        )
 
     (defconst SOME_CONSTANT 3)
 )

diff --git a/docs/en/pact-reference.rst b/docs/en/pact-reference.rst
@@ -253,7 +253,7 @@ Public meta
 
    name: "creationTime"  # Tx creation time, POSIX seconds since epoch (Jan 1 1970 00:00:00 UTC).
    type: integer         # Platform will validate time as within some range of network time.
-   required: true
+   required: false
 
 .. _exec-payload:
 
@@ -1200,7 +1200,7 @@ keys:
        gasLimit: integer gas limit
        gasPrice: decimal gas price
        ttl: integer time-to-live value
-       creationTime: integer tx execution time after offset
+       creationTime: optional integer tx execution time after offset
      type: exec
 
 The continuation request yaml for a public blockchain takes the
@@ -1228,13 +1228,143 @@ following keys:
        gasLimit: integer gas limit
        gasPrice: decimal gas price
        ttl: integer time-to-live value
-       creationTime: integer tx execution time after offset
+       creationTime: optional integer tx execution time after offset
      nonce: optional request nonce, will use current time if not provided
      type: cont
 
 Note that the optional “proof” field only makes sense when using
 cross-chain continuations.
 
+Signing Transactions
+--------------------
+
+As of Pact 3.5.0, the ``pact`` command line tool now has several
+commands to facilitate signing transactions. Here’s a full script
+showing how these commands can be used to prepare an unsigned version of
+the transaction and add signatures to it. This transcript assumes that
+the details of the transaction has been specified in a file called
+``tx.yaml``.
+
+::
+
+   # At some earlier time generate and save some public/private key pairs.
+   pact -g > alice-key.yaml
+   pact -g > bob-key.yaml
+
+   # Convert a transaction into an unsigned prepared form that is signatures can be added to
+   pact -u tx.yaml > tx-unsigned.yaml
+
+   # Sign the prepared transaction with one or more keys
+   cat tx-unsigned.yaml | pact add-sig alice-key.yaml > tx-signed-alice.yaml
+   cat tx-unsigned.yaml | pact add-sig bob-key.yaml > tx-signed-bob.yaml
+
+   # Combine the signatures into a fully signed transaction ready to send to the blockchain
+   pact combine-sigs tx-signed-alice.yaml tx-signed-bob.yaml > tx-final.json
+
+The ``add-sig`` command takes the output of ``pact -u`` on standard
+input and one or more key files as command line arguments. It adds the
+appropriate signatures to to the transaction and prints the result to
+stdout.
+
+The ``combine-sigs`` command takes multiple unsigned (from ``pact -u``)
+and signed (from ``pact add-sig``) transaction files as command line
+arguments and outputs the command and all the signatures on stdout.
+
+Both ``add-sig`` and ``combine-sigs`` will output YAML if the output
+transaction hasn’t accumulated enough signatures to be valid. If all the
+necessary signatures are present, then they will output JSON in final
+form that is ready to be sent to the blockchain on the ```/send``
+endpoint <#send>`__. If you would like to do a test run of the
+transaction, you can use the ``-l`` flag to generate output suitable for
+use with the ```/local`` endpoint <#local>`__.
+
+The above example adds signatures in parallel, but the ``add-sig``
+command can also be used to add signatures sequentially in separate
+steps or all at once in a single step as shown in the following two
+examples:
+
+::
+
+   cat tx-unsigned.yaml | pact add-sig alice-key.yaml | pact add-sig bob-key.yaml
+   cat tx-unsigned.yaml | pact add-sig alice-key.yaml add-sig bob-key.yaml
+
+Offline Signing with a Cold Wallet
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Some cold wallet signing procedures use QR codes to get transaction data
+on and off the cold wallet machine. Since QR codes can transmit a fairly
+limited amount of information these signing commands are also designed
+to work with a more compact data format that doesn’t require the full
+command to generate signatures. Here’s an example of what
+``tx-unsigned.yaml`` might look like in the above example:
+
+::
+
+   hash: KY6RFunty4WazQiCsKsYD-ovu-_XQByfY6scTxi9gQQ
+   sigs:
+     368820f80c324bbc7c2b0610688a7da43e39f91d118732671cd9c7500ff43cca: null
+     6be2f485a7af75fedb4b7f153a903f7e6000ca4aa501179c91a2450b777bd2a7: null
+   cmd: '{"networkId":"mainnet01","payload":{"exec":{"data":{"ks":{"pred":"keys-all","keys":["368820f80c324bbc7c2b0610688a7da43e39f91d118732671cd9c7500ff43cca"]}},"code":"(coin.transfer-create \"alice\" \"bob\" (read-keyset \"ks\") 100.1)\n(coin.transfer \"bob\" \"alice\" 0.1)"}},"signers":[{"pubKey":"6be2f485a7af75fedb4b7f153a903f7e6000ca4aa501179c91a2450b777bd2a7","clist":[{"args":["alice","bob",100.1],"name":"coin.TRANSFER"},{"args":[],"name":"coin.GAS"}]},{"pubKey":"368820f80c324bbc7c2b0610688a7da43e39f91d118732671cd9c7500ff43cca","clist":[{"args":["bob","alice",0.1],"name":"coin.TRANSFER"}]}],"meta":{"creationTime":1580316382,"ttl":7200,"gasLimit":1200,"chainId":"0","gasPrice":1.0e-5,"sender":"alice"},"nonce":"2020-01-29 16:46:22.916695 UTC"}'
+
+To get a condensed version for signing on a cold wallet all you have to
+do is drop the ``cmd`` field. This can be done manually or scripted with
+``cat tx-unsigned.yaml | grep -v "^cmd:"``. The result would look like
+this:
+
+::
+
+   hash: KY6RFunty4WazQiCsKsYD-ovu-_XQByfY6scTxi9gQQ
+   sigs:
+     368820f80c324bbc7c2b0610688a7da43e39f91d118732671cd9c7500ff43cca: null
+     6be2f485a7af75fedb4b7f153a903f7e6000ca4aa501179c91a2450b777bd2a7: null
+
+Keep in mind that when you sign these condensed versions, you won’t be
+able to submit the output directly to the blockchain. You’ll have to use
+``combine-sigs`` to combine those signatures with the original
+``tx-unsigned.yaml`` file which has the full command.
+
+Detached Signature Transaction Format
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The YAML input expected by ``pact -u`` is similar to the `Public
+Blockchain YAML format <#request-yaml-public-chain>`__ described above
+with one major difference. Instead of the ``keyPairs`` field which
+requires both the public and secret keys, ``pact -u`` expects a
+``signers`` field that only needs a public key. This allows signatures
+to be added on incrementally as described above without needing private
+keys to all be present when the transaction is constructed.
+
+Here is an example of how the above ``tx.yaml`` file might look:
+
+::
+
+   code: |-
+     (coin.transfer-create "alice" "bob" (read-keyset "ks") 100.1)
+     (coin.transfer "bob" "alice" 0.1)
+   data:
+     ks:
+       keys: [368820f80c324bbc7c2b0610688a7da43e39f91d118732671cd9c7500ff43cca]
+       pred: "keys-all"
+   publicMeta:
+     chainId: "0"
+     sender: alice
+     gasLimit: 1200
+     gasPrice: 0.0000000001
+     ttl: 7200
+   networkId: "mainnet01"
+   signers:
+     - public: 6be2f485a7af75fedb4b7f153a903f7e6000ca4aa501179c91a2450b777bd2a7
+       caps:
+         - name: "coin.TRANSFER"
+           args: ["alice", "bob", 100.1]
+         - name: "coin.GAS"
+           args: []
+     - public: 368820f80c324bbc7c2b0610688a7da43e39f91d118732671cd9c7500ff43cca
+       caps:
+         - name: "coin.TRANSFER"
+           args: ["bob", "alice", 0.1]
+   type: exec
+
 Concepts
 ========
 

diff --git a/pact.cabal b/pact.cabal
@@ -1,6 +1,6 @@
 cabal-version:       2.2
 name:                pact
-version:             3.4.0
+version:             3.5.0
 synopsis:            Smart contract language library and REPL
 description:
             Pact is a transactional, database-focused, Turing-incomplete, interpreted language for smart contracts,
-Original file line number
+Diff line change
@@ Expand Up @@
     Obtain current pact build version.
     ```lisp
     pact> (pact-version)
-    "3.4.0"
+    "3.5.0"
     ```
     Top level only: this function will fail if used in module code.
@@ Expand Down @@