Merge pull request #238 from oasisprotocol/matevz/docs/tx-format

docs: Document --format parameter

docs/README.md

@@ -1,6 +1,6 @@
 ---
 title: Oasis CLI
-description: Powerful CLI for managing Oasis network, nodes, tokens and dapps
+description: Powerful CLI for managing Oasis networks, nodes, tokens and dApps
 ---
 
 # Oasis Command Line Interface
@@ -12,7 +12,8 @@ binaries from the [GitHub repository].
 It boasts a number of handy features:
 
 - Flexible setup:
-  - supports Mainnet, Testnet, Localnet or any other Oasis network deployment
+  - supports Mainnet, Testnet, Localnet or any other deployment of the Oasis
+    network
   - consensus layer configuration with arbitrary token
   - configuration of custom ParaTimes with arbitrary token
   - connecting to remote (via TCP/IP) or local (Unix socket) Oasis node

docs/account.md

@@ -467,11 +467,17 @@ and for all other prompts it will keep the proposed default values.
 
 ### Output Transaction to File {#output-file}
 
-You can use `--output-file <filename>` parameter to save a transaction to
-a JSON file instead of immediately broadcasting it to the network. Afterwards,
-use the [`transaction`] command to verify and submit the transaction.
+Use `--output-file <filename>` parameter to save the resulting transaction to a
+file instead of broadcasting it to the network. You can then use the
+[`transaction`] command to verify and submit it.
+
+Check out the [`--unsigned`] flag, if you wish to store the unsigned version of
+the transaction and the [`--format`] parameter for a different transaction
+encoding.
 
 [`transaction`]: ./transaction.md
+[`--unsigned`]: #unsigned
+[`--format`]: #format
 
 ### Do Not Sign the Transaction {#unsigned}
 
@@ -490,11 +496,27 @@ setup is ideal when you want to sign a transaction with the
 4. copy it over to the networked machine,
 5. [broadcast the transaction][transaction-submit] on the networked machine.
 
+Use the CBOR format, if you are using a 3rd party tool in step 3 to sign the
+transaction content directly. Check out the [`--format`] parameter to learn
+more.
+
 [`--output-file`]: #output-file
 [transaction-sign]: ./transaction.md#sign
 [transaction-submit]: ./transaction.md#submit
 [offline/air-gapped machine]: https://en.wikipedia.org/wiki/Air_gap_\(networking\)
 
+### Output format {#format}
+
+Use `--format json` or `--format cbor` to select the output file
+format. By default the JSON encoding is selected so that the file is
+human-readable and that 3rd party applications can easily manage it. If you want
+to output the transaction in the same format that will be stored on-chain or you
+are using a 3rd party tool for signing the content of the transaction file
+directly use the CBOR encoding.
+
+This parameter only works together with [`--unsigned`] and/or
+[`--output-file`] parameters.
+
 ### Offline Mode {#offline}
 
 To generate a transaction without accessing the network and also without

docs/transaction.md

@@ -1,6 +1,6 @@
 ---
 title: Transaction
-description: Using CLI to submit or decode a transaction
+description: Use CLI to decode, verify, sign and submit a transaction
 ---
 
 # Transaction Tools
@@ -33,23 +33,24 @@ We can decode and verify the transaction as follows:
 
 ![code](../examples/transaction/show.out)
 
-Since the signature also includes the [chain domain separation context], it
-will be invalid on other networks such as Mainnet and Oasis CLI will mark it as
-`[INVALID SIGNATURE]`:
+Since the signature depends on the [chain domain separation context], the
+transaction above will be invalid on other networks such as the Mainnet. In this
+case the Oasis CLI will print the `[INVALID SIGNATURE]` warning below the
+signature:
 
 ![code shell](../examples/transaction/show-invalid.in)
 
-![code](../examples/transaction/show-invalid.out)
+![code {4}](../examples/transaction/show-invalid.out)
 
-A similar approach is suitable for ParaTime transactions. Take the following
-transaction which transfers `1.0 TEST` from `test:alice` to `test:bob` inside
-Sapphire ParaTime on Testnet and save it as `testtx2.json`:
+The `show` command is also compatible with ParaTime transactions. Take the
+following transaction which transfers `1.0 TEST` from `test:alice` to `test:bob`
+inside Sapphire ParaTime on the Testnet:
 
 ![code json](../examples/transaction/testtx2.json "testtx2.json")
 
-Oasis CLI will be able to verify the transaction only for the exact network and
-ParaTime combination since both are included inside the chain domain separation
-context of a ParaTime transaction signature.
+The Oasis CLI will be able to verify a transaction only for the **exact network
+and ParaTime combination** since both are used to derive the chain domain
+separation context for signing the transaction.
 
 ![code shell](../examples/transaction/show-paratime-tx.in)