From 3c795cb555b58a347f4567c3f9b7d41f099db503 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matev=C5=BE=20Jekovec?= Date: Mon, 13 May 2024 15:31:38 +0200 Subject: [PATCH] docs: Document --format parameter --- docs/README.md | 5 +++-- docs/account.md | 28 +++++++++++++++++++++++++--- docs/transaction.md | 23 ++++++++++++----------- 3 files changed, 40 insertions(+), 16 deletions(-) diff --git a/docs/README.md b/docs/README.md index 31a06f78..1af3618e 100644 --- a/docs/README.md +++ b/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 diff --git a/docs/account.md b/docs/account.md index a8487567..79219ad3 100644 --- a/docs/account.md +++ b/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 ` 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 ` 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 diff --git a/docs/transaction.md b/docs/transaction.md index 539fddb1..c1f1c0aa 100644 --- a/docs/transaction.md +++ b/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)