Move Subxt crate into a subfolder (#424)

* move into subfolder step 1

* Make folders a workspace again

* Move examples into their own workspace crate to make them more visible and easier to run

* clippy fix

* newline

* tweak releasing steps for folder move

* reference exampels more clearly in top level readme

examples/examples/custom_config.rs

@@ -0,0 +1,70 @@
+// Copyright 2019-2022 Parity Technologies (UK) Ltd.
+// This file is part of subxt.
+//
+// subxt is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// subxt is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with subxt.  If not, see <http://www.gnu.org/licenses/>.
+
+use sp_keyring::AccountKeyring;
+use subxt::{
+    ClientBuilder,
+    Config,
+    DefaultConfig,
+    DefaultExtra,
+    PairSigner,
+};
+
+#[subxt::subxt(runtime_metadata_path = "examples/polkadot_metadata.scale")]
+pub mod polkadot {}
+
+/// Custom [`Config`] impl where the default types for the target chain differ from the
+/// [`DefaultConfig`]
+#[derive(Clone, Debug, Default, Eq, PartialEq)]
+pub struct MyConfig;
+impl Config for MyConfig {
+    // This is different from the default `u32`.
+    //
+    // *Note* that in this example it does differ from the actual `Index` type in the
+    // polkadot runtime used, so some operations will fail. Normally when using a custom `Config`
+    // impl types MUST match exactly those used in the actual runtime.
+    type Index = u64;
+    type BlockNumber = <DefaultConfig as Config>::BlockNumber;
+    type Hash = <DefaultConfig as Config>::Hash;
+    type Hashing = <DefaultConfig as Config>::Hashing;
+    type AccountId = <DefaultConfig as Config>::AccountId;
+    type Address = <DefaultConfig as Config>::Address;
+    type Header = <DefaultConfig as Config>::Header;
+    type Signature = <DefaultConfig as Config>::Signature;
+    type Extrinsic = <DefaultConfig as Config>::Extrinsic;
+}
+
+#[async_std::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let api = ClientBuilder::new()
+        .build()
+        .await?
+        .to_runtime_api::<polkadot::RuntimeApi<MyConfig, DefaultExtra<MyConfig>>>();
+
+    let signer = PairSigner::new(AccountKeyring::Alice.pair());
+    let dest = AccountKeyring::Bob.to_account_id().into();
+
+    let hash = api
+        .tx()
+        .balances()
+        .transfer(dest, 10_000)
+        .sign_and_submit(&signer)
+        .await?;
+
+    println!("Balance transfer extrinsic submitted: {}", hash);
+
+    Ok(())
+}

examples/examples/custom_type_derives.rs

@@ -0,0 +1,34 @@
+// Copyright 2019-2022 Parity Technologies (UK) Ltd.
+// This file is part of subxt.
+//
+// subxt is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// subxt is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with subxt.  If not, see <http://www.gnu.org/licenses/>.
+
+#![allow(clippy::redundant_clone)]
+
+#[subxt::subxt(
+    runtime_metadata_path = "examples/polkadot_metadata.scale",
+    // We can add (certain) custom derives to the generated types by providing
+    // a comma separated list to the below attribute. Most useful for adding `Clone`:
+    generated_type_derives = "Clone, Hash"
+)]
+pub mod polkadot {}
+
+use polkadot::runtime_types::frame_support::PalletId;
+
+#[async_std::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let pallet_id = PalletId([1u8; 8]);
+    let _ = pallet_id.clone();
+    Ok(())
+}

examples/examples/fetch_all_accounts.rs

@@ -0,0 +1,49 @@
+// Copyright 2019-2022 Parity Technologies (UK) Ltd.
+// This file is part of subxt.
+//
+// subxt is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// subxt is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with subxt.  If not, see <http://www.gnu.org/licenses/>.
+
+//! To run this example, a local polkadot node should be running.
+//!
+//! E.g.
+//! ```bash
+//! curl "https://github.com/paritytech/polkadot/releases/download/v0.9.11/polkadot" --output /usr/local/bin/polkadot --location
+//! polkadot --dev --tmp
+//! ```
+
+use subxt::{
+    ClientBuilder,
+    DefaultConfig,
+    DefaultExtra,
+};
+
+#[subxt::subxt(runtime_metadata_path = "examples/polkadot_metadata.scale")]
+pub mod polkadot {}
+
+#[async_std::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    env_logger::init();
+
+    let api = ClientBuilder::new()
+        .build()
+        .await?
+        .to_runtime_api::<polkadot::RuntimeApi<DefaultConfig, DefaultExtra<DefaultConfig>>>();
+
+    let mut iter = api.storage().system().account_iter(None).await?;
+
+    while let Some((key, account)) = iter.next().await? {
+        println!("{}: {}", hex::encode(key), account.data.free);
+    }
+    Ok(())
+}

examples/examples/fetch_remote.rs

@@ -0,0 +1,51 @@
+// Copyright 2019-2022 Parity Technologies (UK) Ltd.
+// This file is part of subxt.
+//
+// subxt is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// subxt is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with subxt.  If not, see <http://www.gnu.org/licenses/>.
+
+use subxt::{
+    ClientBuilder,
+    DefaultConfig,
+    DefaultExtra,
+};
+
+#[subxt::subxt(runtime_metadata_path = "examples/polkadot_metadata.scale")]
+pub mod polkadot {}
+
+#[async_std::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    env_logger::init();
+
+    let api = ClientBuilder::new()
+        .set_url("wss://rpc.polkadot.io:443")
+        .build()
+        .await?
+        .to_runtime_api::<polkadot::RuntimeApi<DefaultConfig, DefaultExtra<DefaultConfig>>>();
+
+    let block_number = 1;
+
+    let block_hash = api
+        .client
+        .rpc()
+        .block_hash(Some(block_number.into()))
+        .await?;
+
+    if let Some(hash) = block_hash {
+        println!("Block hash for block number {}: {}", block_number, hash);
+    } else {
+        println!("Block number {} not found.", block_number);
+    }
+
+    Ok(())
+}

examples/examples/polkadot_balance_transfer.rs

@@ -0,0 +1,57 @@
+// Copyright 2019-2022 Parity Technologies (UK) Ltd.
+// This file is part of subxt.
+//
+// subxt is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// subxt is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with subxt.  If not, see <http://www.gnu.org/licenses/>.
+
+//! To run this example, a local polkadot node should be running.
+//!
+//! E.g.
+//! ```bash
+//! curl "https://github.com/paritytech/polkadot/releases/download/v0.9.11/polkadot" --output /usr/local/bin/polkadot --location
+//! polkadot --dev --tmp
+//! ```
+
+use sp_keyring::AccountKeyring;
+use subxt::{
+    ClientBuilder,
+    DefaultConfig,
+    DefaultExtra,
+    PairSigner,
+};
+
+#[subxt::subxt(runtime_metadata_path = "examples/polkadot_metadata.scale")]
+pub mod polkadot {}
+
+#[async_std::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    env_logger::init();
+
+    let signer = PairSigner::new(AccountKeyring::Alice.pair());
+    let dest = AccountKeyring::Bob.to_account_id().into();
+
+    let api = ClientBuilder::new()
+        .build()
+        .await?
+        .to_runtime_api::<polkadot::RuntimeApi<DefaultConfig, DefaultExtra<DefaultConfig>>>();
+    let hash = api
+        .tx()
+        .balances()
+        .transfer(dest, 10_000)
+        .sign_and_submit(&signer)
+        .await?;
+
+    println!("Balance transfer extrinsic submitted: {}", hash);
+
+    Ok(())
+}

examples/examples/submit_and_watch.rs

@@ -0,0 +1,200 @@
+// Copyright 2019-2022 Parity Technologies (UK) Ltd.
+// This file is part of subxt.
+//
+// subxt is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// subxt is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with subxt.  If not, see <http://www.gnu.org/licenses/>.
+
+//! To run this example, a local polkadot node should be running.
+//!
+//! E.g.
+//! ```bash
+//! curl "https://github.com/paritytech/polkadot/releases/download/v0.9.11/polkadot" --output /usr/local/bin/polkadot --location
+//! polkadot --dev --tmp
+//! ```
+
+use futures::StreamExt;
+use sp_keyring::AccountKeyring;
+use subxt::{
+    ClientBuilder,
+    DefaultConfig,
+    DefaultExtra,
+    PairSigner,
+};
+
+#[subxt::subxt(runtime_metadata_path = "examples/polkadot_metadata.scale")]
+pub mod polkadot {}
+
+#[async_std::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    env_logger::init();
+
+    simple_transfer().await?;
+    simple_transfer_separate_events().await?;
+    handle_transfer_events().await?;
+
+    Ok(())
+}
+
+/// This is the highest level approach to using this API. We use `wait_for_finalized_success`
+/// to wait for the transaction to make it into a finalized block, and also ensure that the
+/// transaction was successful according to the associated events.
+async fn simple_transfer() -> Result<(), Box<dyn std::error::Error>> {
+    let signer = PairSigner::new(AccountKeyring::Alice.pair());
+    let dest = AccountKeyring::Bob.to_account_id().into();
+
+    let api = ClientBuilder::new()
+        .build()
+        .await?
+        .to_runtime_api::<polkadot::RuntimeApi<DefaultConfig, DefaultExtra<_>>>();
+
+    let balance_transfer = api
+        .tx()
+        .balances()
+        .transfer(dest, 10_000)
+        .sign_and_submit_then_watch(&signer)
+        .await?
+        .wait_for_finalized_success()
+        .await?;
+
+    let transfer_event =
+        balance_transfer.find_first_event::<polkadot::balances::events::Transfer>()?;
+
+    if let Some(event) = transfer_event {
+        println!("Balance transfer success: value: {:?}", event.2);
+    } else {
+        println!("Failed to find Balances::Transfer Event");
+    }
+    Ok(())
+}
+
+/// This is very similar to `simple_transfer`, except to show that we can handle
+/// waiting for the transaction to be finalized separately from obtaining and checking
+/// for success on the events.
+async fn simple_transfer_separate_events() -> Result<(), Box<dyn std::error::Error>> {
+    let signer = PairSigner::new(AccountKeyring::Alice.pair());
+    let dest = AccountKeyring::Bob.to_account_id().into();
+
+    let api = ClientBuilder::new()
+        .build()
+        .await?
+        .to_runtime_api::<polkadot::RuntimeApi<DefaultConfig, DefaultExtra<_>>>();
+
+    let balance_transfer = api
+        .tx()
+        .balances()
+        .transfer(dest, 10_000)
+        .sign_and_submit_then_watch(&signer)
+        .await?
+        .wait_for_finalized()
+        .await?;
+
+    // Now we know it's been finalized, we can get hold of a couple of
+    // details, including events. Calling `wait_for_finalized_success` is
+    // equivalent to calling `wait_for_finalized` and then `wait_for_success`:
+    let _events = balance_transfer.wait_for_success().await?;
+
+    // Alternately, we could just `fetch_events`, which grabs all of the events like
+    // the above, but does not check for success, and leaves it up to you:
+    let events = balance_transfer.fetch_events().await?;
+
+    let failed_event =
+        events.find_first_event::<polkadot::system::events::ExtrinsicFailed>()?;
+
+    if let Some(_ev) = failed_event {
+        // We found a failed event; the transfer didn't succeed.
+        println!("Balance transfer failed");
+    } else {
+        // We didn't find a failed event; the transfer succeeded. Find
+        // more details about it to report..
+        let transfer_event =
+            events.find_first_event::<polkadot::balances::events::Transfer>()?;
+        if let Some(event) = transfer_event {
+            println!("Balance transfer success: value: {:?}", event.2);
+        } else {
+            println!("Failed to find Balances::Transfer Event");
+        }
+    }
+
+    Ok(())
+}
+
+/// If we need more visibility into the state of the transaction, we can also ditch
+/// `wait_for_finalized` entirely and stream the transaction progress events, handling
+/// them more manually.
+async fn handle_transfer_events() -> Result<(), Box<dyn std::error::Error>> {
+    let signer = PairSigner::new(AccountKeyring::Alice.pair());
+    let dest = AccountKeyring::Bob.to_account_id().into();
+
+    let api = ClientBuilder::new()
+        .build()
+        .await?
+        .to_runtime_api::<polkadot::RuntimeApi<DefaultConfig, DefaultExtra<_>>>();
+
+    let mut balance_transfer_progress = api
+        .tx()
+        .balances()
+        .transfer(dest, 10_000)
+        .sign_and_submit_then_watch(&signer)
+        .await?;
+
+    while let Some(ev) = balance_transfer_progress.next().await {
+        let ev = ev?;
+        use subxt::TransactionStatus::*;
+
+        // Made it into a block, but not finalized.
+        if let InBlock(details) = ev {
+            println!(
+                "Transaction {:?} made it into block {:?}",
+                details.extrinsic_hash(),
+                details.block_hash()
+            );
+
+            let events = details.wait_for_success().await?;
+            let transfer_event =
+                events.find_first_event::<polkadot::balances::events::Transfer>()?;
+
+            if let Some(event) = transfer_event {
+                println!(
+                    "Balance transfer is now in block (but not finalized): value: {:?}",
+                    event.2
+                );
+            } else {
+                println!("Failed to find Balances::Transfer Event");
+            }
+        }
+        // Finalized!
+        else if let Finalized(details) = ev {
+            println!(
+                "Transaction {:?} is finalized in block {:?}",
+                details.extrinsic_hash(),
+                details.block_hash()
+            );
+
+            let events = details.wait_for_success().await?;
+            let transfer_event =
+                events.find_first_event::<polkadot::balances::events::Transfer>()?;
+
+            if let Some(event) = transfer_event {
+                println!("Balance transfer success: value: {:?}", event.2);
+            } else {
+                println!("Failed to find Balances::Transfer Event");
+            }
+        }
+        // Report other statuses we see.
+        else {
+            println!("Current transaction status: {:?}", ev);
+        }
+    }
+
+    Ok(())
+}

examples/examples/transfer_subscribe.rs

@@ -0,0 +1,70 @@
+// Copyright 2019-2022 Parity Technologies (UK) Ltd.
+// This file is part of subxt.
+//
+// subxt is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// subxt is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with subxt.  If not, see <http://www.gnu.org/licenses/>.
+
+//! To run this example, a local polkadot node should be running.
+//!
+//! E.g.
+//! ```bash
+//! curl "https://github.com/paritytech/polkadot/releases/download/v0.9.11/polkadot" --output /usr/local/bin/polkadot --location
+//! polkadot --dev --tmp
+//! ```
+
+use sp_keyring::AccountKeyring;
+use subxt::{
+    ClientBuilder,
+    DefaultConfig,
+    DefaultExtra,
+    EventSubscription,
+    PairSigner,
+};
+
+#[subxt::subxt(runtime_metadata_path = "examples/polkadot_metadata.scale")]
+pub mod polkadot {}
+
+#[async_std::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    env_logger::init();
+
+    let signer = PairSigner::new(AccountKeyring::Alice.pair());
+    let dest = AccountKeyring::Bob.to_account_id().into();
+
+    let api = ClientBuilder::new()
+        .build()
+        .await?
+        .to_runtime_api::<polkadot::RuntimeApi<DefaultConfig, DefaultExtra<DefaultConfig>>>();
+
+    let sub = api.client.rpc().subscribe_events().await?;
+    let decoder = api.client.events_decoder();
+    let mut sub = EventSubscription::<DefaultConfig>::new(sub, decoder);
+    sub.filter_event::<polkadot::balances::events::Transfer>();
+
+    api.tx()
+        .balances()
+        .transfer(dest, 10_000)
+        .sign_and_submit(&signer)
+        .await?;
+
+    let raw = sub.next().await.unwrap().unwrap();
+    let event = <polkadot::balances::events::Transfer as subxt::codec::Decode>::decode(
+        &mut &raw.data[..],
+    );
+    if let Ok(e) = event {
+        println!("Balance transfer success: value: {:?}", e.2);
+    } else {
+        println!("Failed to subscribe to Balances::Transfer Event");
+    }
+    Ok(())
+}