Added more documentation and block, and tx payment examples

build_sdk.sh

@@ -10,5 +10,5 @@ cargo check --target wasm32-unknown-unknown --no-default-features --features "wa
 
 # Examples
 cd ./examples
-cargo check
-cargo check --no-default-features
+cargo check --bins
+cargo check --bins --no-default-features

docs/src/SUMMARY.md

@@ -1,10 +1,19 @@
 # Summary
 
+- [Basics](./basics_index.md)
+    - [Transaction 1](./basics_transaction_1.md)
+    - [Transaction 1.1](./basics_transaction_1_1.md)
+    - [Transaction 2](./basics_transaction_2.md)
+    - [Transaction 2.1](./basics_transaction_2_1.md)
+    - [Transaction 3](./basics_transaction_3.md)
+    - [Transaction 4](./basics_transaction_4.md)
 - [RPC](./rpc.md)
 - [Storage](./storage.md)
 - [Account Nonce](./account_nonce.md)
 - [Transaction Options](./transaction_options.md)
+- [Transaction Payment](./transaction_payment.md)
 - [Batch](./batch.md)
+- [Block](./block.md)
 - [Data Submission](./data_submission.md)
 - [Events](./events.md)
 - [Transactions](./transactions.md)

docs/src/basics_index.md

@@ -0,0 +1,3 @@
+# Basics
+
+The goal of this guide is to learn how to use subxt and then in a iterative way enhance and tidy the code using avail-rust SDK.

docs/src/basics_transaction_1.md

@@ -0,0 +1,121 @@
+# Transaction - 1
+
+Every transaction consists of the following parts:
+- Signature
+- Payload
+- Transaction Parameters
+
+The Signature defines who is accountable and who's funds will be taken in order to pay for transaction execution.   
+The Payload is the function (together with the data) that will be executed.   
+The Transaction Parameters define additional information about our transaction. Here we would say how much tip we want to give, what nonce to use, etc.   
+
+In order for our transaction to be executed we need the following parts:
+- Establish WebSocket or HTTP connection with a network
+- Way to submit a transaction
+- Way to check if that transaction was successfully included
+
+## Setting up the stage
+Our initial setup will have nothing more than the bare minimum to compile our code.   
+Most of the types that we need are included in the `prelude` import collection but because we are not going to use any of it (for now) we will have to manually import modules.
+
+All the future code that we will write will go inside the `main` function.
+
+```rs
+use avail_rust::error::ClientError;
+
+#[tokio::main]
+async fn main() -> Result<(), ClientError> {
+    // Code goes here
+
+    Ok(())
+}
+```
+
+## Connection
+The first thing that we need to do is to establish a connection with an existing network. For the sake of brevity, we will cover only how to do it using websockets but you can find in other examples on how to do it either using HTTP or a custom solution.
+
+
+```rs
+{{#include ./../../examples/docs/basics_1/main.rs:connection}}
+```
+
+`rpc_client` is a low level API that allows us to communicate with our network via rpc calls.   
+`online_client` is a higher level API that provides many helper functions and abstractions.
+
+## Accounts
+> An account represents an identity—usually of a person or an organization—that is capable of making transactions or holding funds.
+> In general, every account has an owner who possesses a public and private key pair. The private key is a cryptographically-secure sequence of randomly-generated numbers. For human readability, the private key generates a random sequence of words called a secret seed phrase or mnemonic.  
+> [Substrate - Accounts, Addresses, Keys](https://docs.substrate.io/learn/accounts-addresses-keys/)
+
+To create an account we paste our secret seed as an argument to `SecretUri` and then pass that `Keypair`. In this case, we will use the default development account named `Alice`.   
+In production you would pass your secret seed via env variable or read it from file.
+
+For Bob use `//Bob`, for Eve use `//Eve`, etc.
+
+```rs
+{{#include ./../../examples/docs/basics_1/main.rs:accounts}}
+```
+
+## Payload
+Payload defines what operation will be executed on the chain. Payload consists of three components:
+- Pallet Name
+- Call Name
+- Call Data
+
+What you need to know is that all the payloads are defines in the following path `avail_rust::avail::*::calls::types::**;` where `*` represents the pallet name and `**` represents the call type.   
+For more examples go to the next page.
+
+```rs
+{{#include ./../../examples/docs/basics_1/main.rs:payload}}
+```
+
+## Transaction Parameters
+There are four transaction parameters:
+- nonce
+- app_id
+- tip
+- mortality
+
+Manually building the transaction parameters is a tedious and convoluted job so here we are using a helper object to do that for us.  
+With the `Options` object we can set what parameters we want to use and with calling `build()` it populates all the non-set params with default values.   
+Here are the default values for all the parameters:
+- nonce: It uses the best block nonce and it increments it if there are existing transaction in the tx pool with the same nonce
+- app_id: 0
+- tip: 0
+- mortality: The transaction will be alive for 32 blocks starting from current best block hash(height)
+
+```rs
+{{#include ./../../examples/docs/basics_1/main.rs:params}}
+```
+
+## Signature
+Adding signature to an existing payload and transaction params allows us to build an transaction that is ready to be submitted.
+
+```rs
+{{#include ./../../examples/docs/basics_1/main.rs:signature}}
+```
+
+## Submission
+Submission is done by calling `.submit()`. There is another method available as well, `.submit_and_watch()`, but that one isn't working correctly.   
+Submitting a transaction yields back the transaction hash.
+
+```rs
+{{#include ./../../examples/docs/basics_1/main.rs:submission}}
+```
+
+
+## Watcher
+Just because we have submitted our transaction it doesn't mean it was successful or  that it got executed at all.   
+We need to implement a `watcher` that will check the next N blocks to see if our tx hash is included in the block.
+
+Once found, we need to search for the `ExtrinsicSuccess` event in order to determine if the transaction was successful or not.
+
+```rs
+{{#include ./../../examples/docs/basics_1/main.rs:watcher}}
+```
+
+
+## Source Code 
+```rs
+{{#include ./../../examples/docs/basics_1/main.rs}}
+```

docs/src/basics_transaction_1_1.md

@@ -0,0 +1,7 @@
+# Transaction - 1.1
+
+Here you can find additional examples on how to correctly construct the payload.
+
+```rs
+{{#include ./../../examples/docs/basics_1_1/main.rs}}
+```

docs/src/basics_transaction_2.md

@@ -0,0 +1,55 @@
+# Transaction - 2
+
+With everything in place, we can slowly replace and tidy up our code.
+
+## Connection
+The first change that we have does was to simplify the creation of online and rpc client. Instead of manually creating them there is an convenient helper function that will set it up for us.   
+
+```rs
+{{#include ./../../examples/docs/basics_2/main.rs:connection}}
+```
+
+The  `reconnecting_api` create an rpc with the following parameters:
+
+```rs
+ReconnectingRpcClient::builder().retry_policy(ExponentialBackoff::from_millis(1000).max_delay(Duration::from_secs(3)).take(3))
+```
+
+## Accounts
+There are already premade accounts available in the SDK interface. There is one as well for Bob, Eve, and Charlie.
+
+```rs
+{{#include ./../../examples/docs/basics_2/main.rs:accounts}}
+```
+
+## Payload
+Manually passing the pallet name, call name and call data is error prone and that's why there is an better way.   
+All the payloads are defined in the following path `avail_rust::avail::tx().*().**(data)` where `*` is the pallet name and `**` is the call type.   
+For more examples go to the next page.
+
+```rs
+{{#include ./../../examples/docs/basics_2/main.rs:payload}}
+```
+
+## Transaction Parameters, Signature, Submission
+Transaction parameters, signature, and submission can be combined all into one single call.   
+Because we are using the default transaction parameters, we are passing `None` as the argument. If we wish to alter the parameters, we would pass an optional `Options` object.
+
+```rs
+{{#include ./../../examples/docs/basics_2/main.rs:signsend}}
+```
+
+## Watcher
+Just like the rest, the watching part can be abstracted as well.   
+Finding if a transaction was successful or not is now just a matter of calling `is_successful()`. If the transaction failed, it will return an error with the description on why it failed.   
+The last arguments, `Some(3)`, tells the watcher to read the next 4 (this is not a typo, it's X + 1) blocks and if none of the contains the target transaction hash it will return an error.
+
+```rs
+{{#include ./../../examples/docs/basics_2/main.rs:watcher}}
+```
+
+
+## Source Code 
+```rs
+{{#include ./../../examples/docs/basics_2/main.rs}}
+```

docs/src/basics_transaction_2_1.md

@@ -0,0 +1,7 @@
+# Transaction - 2.1
+
+Here you can find additional examples on how to correctly construct the payload.
+
+```rs
+{{#include ./../../examples/docs/basics_2_1/main.rs}}
+```

docs/src/basics_transaction_3.md

@@ -0,0 +1,62 @@
+# Transaction - 3
+We are not done yet.
+
+## Setting up the stage
+Here we are using the prelude import to import all the necessary type declarations.
+
+```rs
+use avail_rust::prelude::*;
+
+#[tokio::main]
+async fn main() -> Result<(), ClientError> {
+    // Code goes here
+
+    Ok(())
+}
+```
+
+## Connection
+Both online_client and rpc_client can be grouped together and now we are using a wrapper to get the local node endpoint instead of writing it manually.   
+Together with `local_endpoint` we have the following other endpoints:
+- `local_http_endpoint`
+- `turing_endpoint`
+- `turing_http_endpoint`
+- `mainnet_endpoint`
+- `mainnet_http_endpoint`
+
+```rs
+{{#include ./../../examples/docs/basics_3/main.rs:connection}}
+```
+
+`new()` method will use a reconnecting websocket rpc. If just HTTP is needed then `new_http()` will do the trick otherwise for custom clients `new_custom(online_client: AOnlineClient, rpc_client: RpcClient)` can be used.
+
+## Payload
+Payload creation has been abstracted away and can now be accessed via `sdk.tx.*.**` path where `*` is pallet name and `**` is call name. Not all transaction have been abstracted away and for some you will still need to use the following path `avail_rust::avail::tx().*().**()`. 
+
+```rs
+{{#include ./../../examples/docs/basics_3/main.rs:payload}}
+```
+
+The object that is returned by the interface has many different helper functions attach to it. Make sure to check them out. 
+
+For some of them you will need to import either `avail_rust::transaction::WebSocket` or `avail_rust::transaction::HTTP` in order to get access to the desired `execute_*` call.   
+The prelude import automatically imports the `WebSocket` one and if that's not desired then you will need avoid prelude import and manually import all the type declarations.
+
+## Transaction Parameters, Signature, Submission, Watcher
+The watcher is now combined with transaction submission. We can now choose if we want to wait for block inclusion, block finalization, and or fire and forget.   
+If we choose to wait, the system will automatically resubmit our transaction in case it didn't found it the next X blocks by using the same transaction parameters.   
+WebSocket and HTTP interface differ here in types and implementation:
+- WebSocket uses block subscription to fetch blocks.
+- HTTP cannot use block subscription because that's a websocket features thus we are forced to fetch headers every N (set to 3 by default) seconds in order to know if a new block has been produced.
+
+The default 3 seconds (sleep_duration) for HTTP can be configured by calling `execute_and_watch` instead of `execute_and_watch_inclusion` or `execute_and_watch_finalization`.   
+
+```rs
+{{#include ./../../examples/docs/basics_3/main.rs:signsend}}
+```
+
+
+## Source Code 
+```rs
+{{#include ./../../examples/docs/basics_3/main.rs}}
+```

docs/src/basics_transaction_4.md

@@ -0,0 +1,25 @@
+# Transaction - 4
+
+The SDK offer much more than just a couple of helper functions for transaction submission. To get a better understanding on what can be done, check all the other examples, especially the following ones:
+- `Data Submission` - This one is a must
+- `Block`
+- `Transactions`
+- `Events`
+
+Not everything is shown in our examples. Open the SDK and take a look what interfaces are available.
+
+## Events and Block
+Here is just a sneak peak on the events and block api that we offer.
+
+```rs
+{{#include ./../../examples/docs/basics_4/main.rs:event}}
+```
+
+```rs
+{{#include ./../../examples/docs/basics_4/main.rs:block}}
+```
+
+## Source Code 
+```rs
+{{#include ./../../examples/docs/basics_4/main.rs}}
+```

docs/src/block.md

@@ -0,0 +1,5 @@
+# Batch
+
+```rs
+{{#include ./../../examples/src/block.rs}}
+```

docs/src/transaction_payment.md

@@ -0,0 +1,5 @@
+# Transaction Payment
+
+```rs
+{{#include ./../../examples/src/transaction_payment.rs}}
+```

examples/Cargo.toml

@@ -3,6 +3,36 @@
 [package]
 name = "sdk-examples"
 edition = "2021"
+default-run = "sdk-examples"
+
+[[bin]]
+name = "sdk-examples"
+path = "./src/main.rs"
+
+[[bin]]
+name = "docs-basics-1"
+path = "./docs/basics_1/main.rs"
+
+[[bin]]
+name = "docs-basics-1_1"
+path = "./docs/basics_1_1/main.rs"
+
+[[bin]]
+name = "docs-basics-2"
+path = "./docs/basics_2/main.rs"
+
+[[bin]]
+name = "docs-basics-2_1"
+path = "./docs/basics_2_1/main.rs"
+
+[[bin]]
+name = "docs-basics-3"
+path = "./docs/basics_3/main.rs"
+
+[[bin]]
+name = "docs-basics-4"
+path = "./docs/basics_4/main.rs"
+
 
 [dependencies]
 avail-rust = { path = "../." }