make the reference commands into mini-tutorials

Author: brunopgalvao

develop/toolkit/integrations/transaction-construction.md

@@ -7,7 +7,7 @@ description: Understand how to construct, sign, and broadcast transactions in th
 
 ## Introduction
 
-This page will discuss the transaction format in Polkadot and how to create, sign, and broadcast transactions. Like the other pages in this guide, this page demonstrates some of the available tools. 
+This page will discuss the transaction format in Polkadot and how to create, sign, and broadcast transactions as well as highlight some of commands and tools available for integrators.
 
 **Always refer to each tool's documentation when integrating.**
 
@@ -77,45 +77,104 @@ The typical transaction workflow is as follows:
 4. Serialize the signed payload into a transaction.
 5. Submit the serialized transaction.
 
-Parity provides the following tools to help perform these steps.
+Parity provides several tools to help perform these steps.
 
 ## Polkadot-JS Tools
 
 [Polkadot-JS Tools](https://github.com/polkadot-js/tools){target=\_blank} contains a set of command line tools for
-interacting with a Substrate client, including one called "Signer CLI" to create, sign, and
+interacting with a Polkadot SDK client, including one called "Signer CLI" to create, sign, and
 broadcast transactions.
 
+!!!note "Generating SS58 Addresses"
+    For the examples on this page, it may be helpful to generate new accounts for signing purposes.
+    For this, you can use the [Subkey](/polkadot-protocol/basics/accounts/#using-subkey){target=\_blank} CLI tool.
+    ```bash
+    $ subkey --network polkadot generate
+    Secret phrase `pulp gaze fuel ... mercy inherit equal` is account:
+      Secret seed:      0x57450b3e09ba4598 ... ... ... ... ... ... ... .. 219756eeba80bb16
+      Public key (hex): 0x2ca17d26ca376087dc30ed52deb74bf0f64aca96fe78b05ec3e720a72adb1235
+      Account ID:       0x2ca17d26ca376087dc30ed52deb74bf0f64aca96fe78b05ec3e720a72adb1235
+      SS58 Address:     121X5bEgTZcGQx5NZjwuTjqqKoiG8B2wEAvrUFjuw24ZGZf2
+
+    $ subkey --network polkadot generate
+    Secret phrase `exercise auction soft ... obey control easily` is account:
+      Secret seed:      0x5f4bbb9fbb69261a ... ... ... ... ... ... ... .. 4691ed7d1130fbbd
+      Public key (hex): 0xda04de6cd781c98acf0693dfb97c11011938ad22fcc476ed0089ac5aec3fe243
+      Account ID:       0xda04de6cd781c98acf0693dfb97c11011938ad22fcc476ed0089ac5aec3fe243
+      SS58 Address:     15vrtLsCQFG3qRYUcaEeeEih4JwepocNJHkpsrqojqnZPc2y
+    ```
+
 This example will use the `signer submit` command, which will create and submit the transaction. The
 `signer sendOffline` command has the exact same API, but will not broadcast the transaction.
 `submit` and `sendOffline` must be connected to a node to fetch the current metadata and construct a
-valid transaction. Their API has the format:
+valid transaction.
+
+Let's start by installing the Signer CLI:
 
 ```bash
-yarn run:signer <submit|sendOffline> --account <from-account-ss58> --ws <endpoint> <module.method> [param1] [...] [paramX]
+npm install -g @polkadot/signer-cli
 ```
 
-Signing:
+And spinning up a network to test our transactions:
+
+```
+npx @acala-network/chopsticks --config=polkadot -p 9944
+```
+We should get a Polkadot network running on port 9944.
+
+> If you are new to chopsticks, you can checkout the [chopsticks guide](/tutorials/polkadot-sdk/testing/fork-live-chains/){target=\_blank}.
+
+To create a transaction, you need to connect to a chain, enabling the creation of a transaction using the chain's metadata. 
+Here is the format for `submit` or `sendOffline`:
 
 ```bash
-yarn run:signer sign --account <from-account-ss58> --seed <seed> --type <sr25519|ed25519> <payload>
+polkadot-js-signer <submit|sendOffline> --account <from-account-ss58> --ws <endpoint> <module.method> [param1] [...] [paramX]
 ```
 
-For example, let's send 0.5 DOT from `121X5bEgTZcGQx5NZjwuTjqqKoiG8B2wEAvrUFjuw24ZGZf2` to
-`15vrtLsCQFG3qRYUcaEeeEih4JwepocNJHkpsrqojqnZPc2y`.
+And for signing a transaction:
+
+```bash
+polkadot-js-signer sign --account <from-account-ss58> --seed <seed> --type <sr25519|ed25519> <payload>
+```
+
+### Creating a Transaction, Signing, and Submitting
+
+For example, let's send 0.5 DOT from `121X5bEgTZcGQx5NZjwuTjqqKoiG8B2wEAvrUFjuw24ZGZf2` to `15vrtLsCQFG3qRYUcaEeeEih4JwepocNJHkpsrqojqnZPc2y` using `polkadot-js-signer`.
+
+First we call submit to create the transaction and give us the payload to sign:
 
 ```bash
-yarn run:signer submit --account 121X5bEgTZcGQx5NZjwuTjqqKoiG8B2wEAvrUFjuw24ZGZf2 --ws ws://127.0.0.1:9944 balances.transferKeepAlive 15vrtLsCQFG3qRYUcaEeeEih4JwepocNJHkpsrqojqnZPc2y 5000000000
+polkadot-js-signer submit --account 121X5bEgTZcGQx5NZjwuTjqqKoiG8B2wEAvrUFjuw24ZGZf2 --ws ws://127.0.0.1:9944 balances.transferKeepAlive 15vrtLsCQFG3qRYUcaEeeEih4JwepocNJHkpsrqojqnZPc2y 5000000000
 ```
 
-This will return a payload to sign and an input waiting for a signature. Take this payload and use
-your normal signing environment (e.g. air gapped machine, VM, etc.). Sign the payload:
+This will return a payload to sign and an input waiting for a signature. Something like this:
+
+```
+Payload: 0x040300ff4a83f1...a8239139ff3ff7c3f6
+Signature>
+```
+
+Take this payload and use your normal signing environment (e.g. air gapped machine, VM, etc.). In a separate tab in your terminal, sign the payload:
 
 ```bash
-yarn run:signer sign --account 121X5bEgTZcGQx5NZjwuTjqqKoiG8B2wEAvrUFjuw24ZGZf2 --seed "pulp gaze fuel ... mercy inherit equal" --type sr25519 0x040300ff4a83f1...a8239139ff3ff7c3f6
+polkadot-js-signer sign --account 121X5bEgTZcGQx5NZjwuTjqqKoiG8B2wEAvrUFjuw24ZGZf2 --seed "pulp gaze fuel ... mercy inherit equal" --type sr25519 0x040300ff4a83f1...a8239139ff3ff7c3f6
+```
+
+This will output the signature of the transaction:
+```
+Signature: 0xe6facf194a8e...413ce3155c2d1240b
 ```
 
-Save the output and bring it to the machine that you will broadcast from, enter it into `submit`'s
-signature field, and send the transaction (or just return the serialized transaction if using `sendOffline`).
+Paste this signature into the `submit`'s signature field, and send the transaction (or just return the serialized transaction if using `sendOffline`).
+
+By default, submit will create a mortal extrinsic with a lifetime of 50 blocks. 
+Assuming a six-second block time, you will have five minutes to go offline, sign the transaction, paste the signature, and submit the signed transaction.
+
+!!!note "Submitting Pre-Signed Transaction"
+    You can also submit pre-signed transactions, e.g. generated using the `sendOffline` command.
+    ```
+    polkadot-js-signer submit --tx <signedTransaction> --ws <endpoint>
+    ```
 
 ## TxWrapper
 
@@ -126,6 +185,61 @@ Substrate-based chains will have their own `txwrapper-{chain}` implementations.
 [examples](https://github.com/paritytech/txwrapper-core/blob/main/packages/txwrapper-examples/README.md){target=\_blank}
 for a guide.
 
+### Creating a Transaction, Signing, and Submitting
+
+We will need a network to run test the transaction on. 
+Let's use [chopsticks](/tutorials/polkadot-sdk/testing/fork-live-chains/){target=\_blank} for this:
+
+```
+npx @acala-network/chopsticks --config=polkadot -p 9944
+```
+We should get a Polkadot network running on port 9944.
+
+Next we will use the [`TxWrapper example script`](https://github.com/paritytech/txwrapper-core/blob/main/packages/txwrapper-examples/polkadot/src/polkadot.ts){target=\_blank} to create and sign transactions.
+
+For this we will need the [`TxWrapper`](https://github.com/paritytech/txwrapper-core){target=\_blank} library. Let's clone [`TxWrapper`](https://github.com/paritytech/txwrapper-core){target=\_blank}:
+
+```
+git clone https://github.com/paritytech/txwrapper-core
+cd txwrapper-core
+yarn install && yarn build
+cd packages/txwrapper-examples
+```
+
+Build and run the [`TxWrapper Polkadot example script`](https://github.com/paritytech/txwrapper-core/blob/main/packages/txwrapper-examples/polkadot/src/polkadot.ts){target=\_blank}:
+```
+yarn run build
+yarn run polkadot
+```
+
+You will get output like the following:
+```
+Alice's SS58-Encoded Address: 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
+
+Decoded Transaction
+  To: 14E5nqKAp3oAJcmzgZhUD2RcptBeUBScxKHgJKU4HPNcKVf3
+  Amount: "10000000000"
+
+Payload to Sign: 0xa40503008eaf04151687736326c9fea17e25fc5287613693c912909cb226aa4794f26a480700e40b54028500000000b1590f001a00000091b171bb158e2d3848fa23a9f1c25182fb8e20313b2c1eb49219da7a70ce90c3843125cd049613a7edf44b55a01efbabffcd1b962068a82070cff82314b67bbc00
+
+Decoded Transaction
+  To: 14E5nqKAp3oAJcmzgZhUD2RcptBeUBScxKHgJKU4HPNcKVf3
+  Amount: "10000000000"
+
+Signature: 0x01ae703e667b3b444e3613a5f06d16bedf2460a18e52075b47c6442ebc1d316917c6d12e3aa7bbd2f8db76cc859b43134cecb4495613d8d504901de776d0642b82
+
+Transaction to Submit: 0x45028400d43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d01ae703e667b3b444e3613a5f06d16bedf2460a18e52075b47c6442ebc1d316917c6d12e3aa7bbd2f8db76cc859b43134cecb4495613d8d504901de776d0642b8285000000000503008eaf04151687736326c9fea17e25fc5287613693c912909cb226aa4794f26a480700e40b5402
+
+Expected Tx Hash: 0xa12126a095b38f0c70331be78743329a851e33839f9b2f93a7ecc34541507891
+Actual Tx Hash: 0xa12126a095b38f0c70331be78743329a851e33839f9b2f93a7ecc34541507891
+
+Decoded Transaction
+  To: 14E5nqKAp3oAJcmzgZhUD2RcptBeUBScxKHgJKU4HPNcKVf3
+  Amount: "10000000000"
+```
+
+The [`TxWrapper example script`](https://github.com/paritytech/txwrapper-core/blob/main/packages/txwrapper-examples/polkadot/src/polkadot.ts){target=\_blank} includes many of the reference examples below:
+
 **Import a private key**
 
 ```ts
@@ -219,33 +333,6 @@ import { getTxHash } from ‘@substrate/txwrapper-polkadot’;
 const txHash = getTxHash(signedTx);
 ```
 
-## Submitting a Signed Payload
-
-There are several ways to submit a signed payload:
-
-1. Signer CLI (`yarn run:signer submit --tx <signed-transaction> --ws <endpoint>`)
-1. [Substrate API Sidecar](https://docs.polkadot.com/develop/toolkit/api-libraries/sidecar/#sidecar-api){target=\_blank}
-1. [RPC](https://docs.polkadot.com/develop/toolkit/api-libraries/){target=\_blank} with `author_submitExtrinsic` or
-   `author_submitAndWatchExtrinsic`, the latter of which will subscribe you to events to be notified
-   as a transaction gets validated and included in the chain.
+## Additional Libraries for Submitting a Transaction
 
-## Example Addresses
-
-Some addresses to use in the examples. See
-[Subkey documentation](https://docs.polkadot.com/polkadot-protocol/basics/accounts/#using-subkey){target=\_blank}.
-
-```bash
-$ subkey --network polkadot generate
-Secret phrase `pulp gaze fuel ... mercy inherit equal` is account:
-  Secret seed:      0x57450b3e09ba4598 ... ... ... ... ... ... ... .. 219756eeba80bb16
-  Public key (hex): 0x2ca17d26ca376087dc30ed52deb74bf0f64aca96fe78b05ec3e720a72adb1235
-  Account ID:       0x2ca17d26ca376087dc30ed52deb74bf0f64aca96fe78b05ec3e720a72adb1235
-  SS58 Address:     121X5bEgTZcGQx5NZjwuTjqqKoiG8B2wEAvrUFjuw24ZGZf2
-
-$ subkey --network polkadot generate
-Secret phrase `exercise auction soft ... obey control easily` is account:
-  Secret seed:      0x5f4bbb9fbb69261a ... ... ... ... ... ... ... .. 4691ed7d1130fbbd
-  Public key (hex): 0xda04de6cd781c98acf0693dfb97c11011938ad22fcc476ed0089ac5aec3fe243
-  Account ID:       0xda04de6cd781c98acf0693dfb97c11011938ad22fcc476ed0089ac5aec3fe243
-  SS58 Address:     15vrtLsCQFG3qRYUcaEeeEih4JwepocNJHkpsrqojqnZPc2y
-```
+Other than Polkadot JS Tools and TXWrapper, there are several other libraries that can also be used to submit a signed payload such as the [Sidecar API](/develop/toolkit/api-libraries/sidecar/#sidecar-api){target=\_blank} or using RPC calls with `author_submitExtrinsic` or `author_submitAndWatchExtrinsic`, the latter of which will subscribe you to events to be notified as a transaction gets validated and included in the chain. You can see all the available libraries in the [API Libraries](/develop/toolkit/api-libraries/) section of the Polkadot Docs.