Things I wish I knew... (#1374)

* Make a start * Intro * Installation * Flatten * Move METHODS_*.md to substrate/*.md * Basics * Apply suggestions from code review Co-Authored-By: Thibaut Sardan <33178835+Tbaut@users.noreply.github.com> * Substrate links * Create * api.consts * Typo * Typo, ms -> md * types.basics (SIP) * Type basics * api.consts jumps to api.query * Start to api.query * Basic queries * Point starting to actual overview * api.rpc * Derive detour * Query subs & query multi * Apply suggestions from code review Co-Authored-By: Thibaut Sardan <33178835+Tbaut@users.noreply.github.com> * typo * Query extras * Basic transactions * Misplaced , * keyring WIP * Keyring wrap-up * Subs SIP * tx subs more WIP * tx subs * Small types cleanups * Apply suggested changes from @JoshOrndorff * Clarify naked await * tx wrapping WIP * Wrap api.wrap * TS placeholder * [WIP] markers for not-started * Clarifying comments * Additional clarifications * types.extend... well, extended... * Remove *nix * Warp up TypeScript... it is it (for now) * Some small text clarifications * Some cleanups * Cleanups, typos * keyring cleanups * Cleanups * Wrap * api.wrap wrapped... hopefully * typos * Registration typos * typescript typos, hope I caught most...
2019-09-11 17:32:34 +02:00
parent 3e417f4f94
commit 55fb391465
34 changed files with 1088 additions and 32 deletions
@@ -0,0 +1,40 @@
+# Transactions
+
+Transaction endpoints are exposed, as determined by the metadata, on the `api.tx` endpoint. These allow you to submit transactions for inclusion in blocks, be it transfers, setting information or anything else your chain supports.
+
+## Simple transactions
+
+To start off, let's make a balance transfer from Alice to Bob.
+
+```js
+...
+
+// sign and send a transfer from Alice to Bob
+const txHash = await api.tx.balances
+  .transfer(BOB, 12345)
+  .signAndSend(alice);
+
+// show the hash
+console.log(`Submitted with hash ${txHash}`);
+```
+
+We have already become familiar with the `Promise` syntax that is used throughout the API, in this case it is no different. We construct a transaction by calling `balances.transfer(<accountId>, <value>)` with the required params and then as a next step we submit it to the node.
+
+As with all other API operations, the `to` params just needs to be "account-like" and the value params needs to be "number-like", the API will take care of encoding and conversion into the correct format.
+
+The result for this call (we will deal with subscriptions in a short while), is the transaction hash. This is a hash of the data and receiving this does not mean that transaction has been included, but rather only that it has been accepted for propagation by the node. (It can still fail on execution, we will handle this in some of our follow-up sections.)
+
+## Under the hood
+
+Despite the single-line format of `signAndSend`, there is a lot hapenning under the hood (and all of this can be manually provided) -
+
+- Based on the sender, the API will retrieve the `system.accountNonce` to determine the next nonce to use
+- The API will retrieve the current block hash and use it to create a mortal transaction, i.e. the transaction will only be valid for a limited number of blocks (by default this is 5 mins at 6s blocktimes)
+- It will construct a payload and sign this, this includes the `genesisHash`, the `blockHash` for the start of the mortal era as well as the current chain `specVersion`
+- The transaction is submitted to the node
+
+As suggested, you can override all of this, i.e. by retrieving the nonce yourself and passing that as an option, i.e. `signAndSend(alice, { nonce: aliceNonce })`, this could be useful when manually tracking and submitting transactions in bulk.
+
+## Into the keyring we go
+
+With the examples above, the variable `alice` seems to have appeared from thin air. To understand how transactions are signed, we will take a [brief diversion into the keyring](keyring.md) before returning to our regularly scheduled program.