Update README

README.md

@@ -2,10 +2,6 @@
 
 A library to **sub**mit e**xt**rinsics to a [substrate](https://github.com/paritytech/substrate) node via RPC.
 
-### :warning: Health Warning :warning: considered *alpha* after recent changes, API still subject to change
-
-#### See https://github.com/paritytech/subxt/issues/309 for an overview of outstanding issues.
-
 ## Usage
 
 Take a look in the [examples](./examples/examples) folder for various `subxt` usage examples.
@@ -41,15 +37,56 @@ resides ([`CARGO_MANIFEST_DIR`](https://doc.rust-lang.org/cargo/reference/enviro
 
 ### Initializing the API client
 
-API is still a work in progress. See [examples](./examples/examples) for the current usage.
+```rust
+use subxt::{ClientBuilder, DefaultConfig, DefaultExtra};
+
+let api = ClientBuilder::new()
+    .set_url("wss://rpc.polkadot.io:443")
+    .build()
+    .await?
+    .to_runtime_api::<node_runtime::RuntimeApi<DefaultConfig, DefaultExtra<DefaultConfig>>>();
+```
+
+The `RuntimeApi` type is generated by the `subxt` macro from the supplied metadata. This can be parameterized with user
+supplied implementations for the `Config` and `Extra` types, if the default implementations differ from the target
+chain.
 
 ### Querying Storage
 
-API is still a work in progress. See [tests](./subxt/tests/integration/frame) for the current usage.
+Call the generated `RuntimeApi::storage()` method, followed by the `pallet_name()` and then the `storage_item_name()`. 
+
+So in order to query `Balances::TotalIssuance`:
+
+```rust
+let total_issuance = api
+    .storage()
+    .balances()
+    .total_issuance(None)
+    .await
+    .unwrap()
+```
 
 ### Submitting Extrinsics
 
-API is still a work in progress. See [examples](./examples/examples/polkadot_balance_transfer.rs) for the current usage.
+Submit an extrinsic, returning success once the transaction is validated and accepted into the pool:
+
+```rust
+use sp_keyring::AccountKeyring;
+use subxt::PairSigner;
+
+let signer = PairSigner::new(AccountKeyring::Alice.pair());
+let dest = AccountKeyring::Bob.to_account_id().into();
+
+let tx_hash = api
+    .tx()
+    .balances()
+    .transfer(dest, 10_000)
+    .sign_and_submit(&signer)
+    .await?;
+```
+
+For more advanced usage, which can wait for block inclusion and return any events triggered by the extrinsic, see the
+[balance transfer example](./examples/examples/balance_transfer.rs).
 
 ## Integration Testing
 
@@ -66,7 +103,7 @@ cargo install --git https://github.com/paritytech/substrate node-cli --tag=polka
 
 Please add your project to this list via a PR.
 
-- [cargo-contract](https://github.com/paritytech/cargo-contract/pull/79) CLI for interacting with Wasm smart contracts.
+- [cargo-contract](https://github.com/paritytech/cargo-contract/) CLI for interacting with Wasm smart contracts.
 - [xcm-cli](https://github.com/ascjones/xcm-cli) CLI for submitting XCM messages.
 - [phala-pherry](https://github.com/Phala-Network/phala-blockchain/tree/master/standalone/pherry) The relayer between Phala blockchain and the off-chain Secure workers.
 - [crunch](https://github.com/turboflakes/crunch) CLI to claim staking rewards in batch every Era or X hours for substrate-based chains.