From f0f21b57a8a9102de4a59b9c6a2bf37e5b3c46bd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Halil=20Beglerovi=C4=87?= Date: Mon, 29 Aug 2022 16:12:08 +0200 Subject: [PATCH] feat: add predicate example and docs (#541) Co-authored-by: Ahmed Mujkic <32431923+MujkicA@users.noreply.github.com> --- Cargo.toml | 1 + docs/src/SUMMARY.md | 2 + docs/src/getting-started/predicates.md | 15 +++ docs/src/predicates/send-spend-predicate.md | 45 +++++++ examples/predicates/Cargo.toml | 15 +++ examples/predicates/src/lib.rs | 119 ++++++++++++++++++ packages/fuels-signers/src/provider.rs | 1 - packages/fuels/tests/harness.rs | 2 +- .../predicate_signatures/Forc.toml | 7 ++ .../predicate_signatures/src/main.sw | 35 ++++++ 10 files changed, 240 insertions(+), 2 deletions(-) create mode 100644 docs/src/getting-started/predicates.md create mode 100644 docs/src/predicates/send-spend-predicate.md create mode 100644 examples/predicates/Cargo.toml create mode 100644 examples/predicates/src/lib.rs create mode 100644 packages/fuels/tests/test_projects/predicate_signatures/Forc.toml create mode 100644 packages/fuels/tests/test_projects/predicate_signatures/src/main.sw diff --git a/Cargo.toml b/Cargo.toml index 615549dbc8..bc7f5487d7 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -8,6 +8,7 @@ resolver = "2" members = [ "examples/contracts", "examples/cookbook", + "examples/predicates", "examples/providers", "examples/rust_bindings", "examples/types", diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 7f86fd9313..e0d9e7e5ee 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -33,6 +33,8 @@ - [Calling other contracts](./calling-contracts/other-contracts.md) - [Multiple contract calls](./calling-contracts/multicalls.md) - [Estimating cost](./calling-contracts/cost-estimation.md) + - [Predicates](./getting-started/predicates.md) + - [Send and spend funds](./predicates/send-spend-predicate.md) - [Types](./getting-started/types.md) - [Bytes32](./types/bytes32.md) - [Address](./types/address.md) diff --git a/docs/src/getting-started/predicates.md b/docs/src/getting-started/predicates.md new file mode 100644 index 0000000000..26806dbccf --- /dev/null +++ b/docs/src/getting-started/predicates.md @@ -0,0 +1,15 @@ +# Predicates + +Predicates, in Sway, are programs that return a Boolean value, and they do not have any side effects (they are pure). + +## Instantiating predicates + +Similar to contracts, once you've written a predicate in Sway and compiled it with `forc build` (read [here](https://fuellabs.github.io/sway/master/introduction/overview.html) for more on how to work with Sway), you'll get the predicate binary. Using the binary, you can instantiate a `predicate` as shown in the code snippet below: + +```rust,ignore +{{#include ../../../examples/predicates/src/lib.rs:predicate_load_from}} +``` +The created `predicate` instance has two fields. The predicate `byte code` and the predicate `address`. This address is generated from the byte code and is the same as the `P2SH` address used in Bitcoin. Users can seamlessly send assets to the predicate address as they do for any other address on the chain. To spend the predicate funds, the user has to provide the original `byte code` of the predicate together with the `predicate data`. The `predicate data` will be used when executing the `byte code`, and if the predicate is validated successfully, the funds will be accessible. + +In the next section, we show how to interact with a predicate and explore an example where specific signatures are needed to spend the predicate funds. + diff --git a/docs/src/predicates/send-spend-predicate.md b/docs/src/predicates/send-spend-predicate.md new file mode 100644 index 0000000000..9984f7d535 --- /dev/null +++ b/docs/src/predicates/send-spend-predicate.md @@ -0,0 +1,45 @@ +# Send and spend funds from predicates + +Let's consider the following predicate example: + +```rust,ignore +{{#include ../../../packages/fuels/tests/test_projects/predicate_signatures/src/main.sw}} +``` + +This predicate accepts three signatures and matches them to three predefined public keys. The `ec_recover_address` function is used to recover the public key from the signatures. If two of three extracted public keys match the predefined public keys, the funds can be spent. Note that the signature order has to match the order of the predefined public keys. + +Let's use the SDK to interact with the predicate. First, let's create three wallets with specific keys. Their hashed public keys are already hard-coded in the predicate. + +```rust,ignore +{{#include ../../../examples/predicates/src/lib.rs:predicate_wallets}} +``` + +Next, let's add some coins, start a provider and connect it with the wallets. + +```rust,ignore +{{#include ../../../examples/predicates/src/lib.rs:predicate_coins}} +``` + +Now we can load the predicate binary, and prepare some transaction variables. + +```rust,ignore +{{#include ../../../examples/predicates/src/lib.rs:predicate_load}} +``` + +After the predicate address is generated we can send funds to it. Note that we are using the same `transfer` function as we used when sending funds to other wallets. We also make sure that the funds are indeed transferred. + +```rust,ignore +{{#include ../../../examples/predicates/src/lib.rs:predicate_send}} +``` + +To spend the funds that are now locked in the predicate, we have to provide two out of three signatures whose public keys match the ones we defined in the predicate. In this example, the signatures are generated from an array of zeros. + +```rust,ignore +{{#include ../../../examples/predicates/src/lib.rs:predicate_signatures}} +``` + +After generating the signatures, we can send a transaction to spend the predicate funds. We use the `receiver` wallet as the recipient. We have to provide the predicate byte code and the required signatures. As we provide the correct data, we receive the funds and verify that the amount is correct. + +```rust,ignore +{{#include ../../../examples/predicates/src/lib.rs:predicate_spend}} +``` diff --git a/examples/predicates/Cargo.toml b/examples/predicates/Cargo.toml new file mode 100644 index 0000000000..14c69692f8 --- /dev/null +++ b/examples/predicates/Cargo.toml @@ -0,0 +1,15 @@ +[package] +name = "fuels-example-predicates" +version = "0.0.0" +edition = "2021" +publish = false +authors = ["Fuel Labs "] +homepage = "https://fuel.network/" +license = "Apache-2.0" +repository = "https://github.com/FuelLabs/fuels-rs" +description = "Fuel Rust SDK cookbook examples." + +[dependencies] +fuels = { version = "0.20.0", path = "../../packages/fuels" } +rand = "0.8" +tokio = { version = "1.10", features = ["full"] } diff --git a/examples/predicates/src/lib.rs b/examples/predicates/src/lib.rs new file mode 100644 index 0000000000..eac22c5e53 --- /dev/null +++ b/examples/predicates/src/lib.rs @@ -0,0 +1,119 @@ +#[cfg(test)] +mod tests { + use fuels::prelude::Error; + + #[tokio::test] + async fn predicate_example() -> Result<(), Error> { + use fuels::contract::predicate::Predicate; + use fuels::prelude::*; + use fuels::signers::fuel_crypto::SecretKey; + + // ANCHOR: predicate_wallets + let secret_key1: SecretKey = + "0x862512a2363db2b3a375c0d4bbbd27172180d89f23f2e259bac850ab02619301" + .parse() + .unwrap(); + + let secret_key2: SecretKey = + "0x37fa81c84ccd547c30c176b118d5cb892bdb113e8e80141f266519422ef9eefd" + .parse() + .unwrap(); + + let secret_key3: SecretKey = + "0x976e5c3fa620092c718d852ca703b6da9e3075b9f2ecb8ed42d9f746bf26aafb" + .parse() + .unwrap(); + + let mut wallet = WalletUnlocked::new_from_private_key(secret_key1, None); + let mut wallet2 = WalletUnlocked::new_from_private_key(secret_key2, None); + let mut wallet3 = WalletUnlocked::new_from_private_key(secret_key3, None); + let mut receiver = WalletUnlocked::new_random(None); + // ANCHOR_END: predicate_wallets + + // ANCHOR: predicate_coins + let all_coins = [&wallet, &wallet2, &wallet3] + .iter() + .flat_map(|wallet| { + setup_single_asset_coins(wallet.address(), AssetId::default(), 10, 1_000_000) + }) + .collect::>(); + + let (provider, _) = setup_test_provider( + all_coins, + Some(Config { + predicates: true, + utxo_validation: true, + ..Config::local_node() + }), + ) + .await; + + [&mut wallet, &mut wallet2, &mut wallet3, &mut receiver] + .iter_mut() + .for_each(|wallet| wallet.set_provider(provider.clone())); + // ANCHOR_END: predicate_coins + + // ANCHOR: predicate_load + // ANCHOR: predicate_load_from + let predicate = Predicate::load_from( + "../../packages/fuels/tests/test_projects/predicate_signatures/out/debug/predicate_signatures.bin", + )?; + + let predicate_code = predicate.code(); + let predicate_address = predicate.address(); + // ANCHOR_END: predicate_load_from + let amount_to_predicate = 1000; + let asset_id = AssetId::default(); + // ANCHOR_END: predicate_load + + // ANCHOR: predicate_send + wallet + .transfer( + predicate_address, + amount_to_predicate, + asset_id, + TxParameters::default(), + ) + .await?; + + let predicate_balance = provider + .get_asset_balance(predicate.address(), asset_id) + .await?; + assert_eq!(predicate_balance, amount_to_predicate); + // ANCHOR_END: predicate_send + + // ANCHOR: predicate_signatures + let data_to_sign = [0; 32]; + let signature1 = wallet.sign_message(&data_to_sign).await?.to_vec(); + let signature2 = wallet2.sign_message(&data_to_sign).await?.to_vec(); + let signature3 = wallet3.sign_message(&data_to_sign).await?.to_vec(); + + let signatures = vec![signature1, signature2, signature3]; + // ANCHOR_END: predicate_signatures + + // ANCHOR: predicate_spend + let predicate_data = signatures.into_iter().flatten().collect(); + receiver + .receive_from_predicate( + predicate_address, + predicate_code, + amount_to_predicate, + asset_id, + Some(predicate_data), + ) + .await?; + + let receiver_balance_after = provider + .get_asset_balance(receiver.address(), asset_id) + .await?; + assert_eq!(amount_to_predicate, receiver_balance_after); + + let predicate_balance = provider + .get_asset_balance(predicate.address(), asset_id) + .await?; + assert_eq!(predicate_balance, 0); + // ANCHOR_END: predicate_spend + + Ok(()) + } +} diff --git a/packages/fuels-signers/src/provider.rs b/packages/fuels-signers/src/provider.rs index d4ec32c108..7771467c39 100644 --- a/packages/fuels-signers/src/provider.rs +++ b/packages/fuels-signers/src/provider.rs @@ -570,7 +570,6 @@ impl Provider { tolerance: f64, ) -> Result { let gas_used = self.get_gas_used(&self.dry_run_no_validation(tx).await?); - dbg!(gas_used); Ok((gas_used as f64 * (1.0 + tolerance)) as u64) } diff --git a/packages/fuels/tests/harness.rs b/packages/fuels/tests/harness.rs index 271b63b9c3..aebc255004 100644 --- a/packages/fuels/tests/harness.rs +++ b/packages/fuels/tests/harness.rs @@ -3358,7 +3358,7 @@ async fn contract_call_fee_estimation() -> Result<(), Error> { .initialize_counter(42) // Build the ABI call .tx_params(TxParameters::new( Some(10_000), - Some(500), + Some(800), Some(10_000), None, )) diff --git a/packages/fuels/tests/test_projects/predicate_signatures/Forc.toml b/packages/fuels/tests/test_projects/predicate_signatures/Forc.toml new file mode 100644 index 0000000000..0b4071b1d3 --- /dev/null +++ b/packages/fuels/tests/test_projects/predicate_signatures/Forc.toml @@ -0,0 +1,7 @@ +[project] +authors = ["Fuel Labs "] +entry = "main.sw" +license = "Apache-2.0" +name = "predicate_signatures" + +[dependencies] diff --git a/packages/fuels/tests/test_projects/predicate_signatures/src/main.sw b/packages/fuels/tests/test_projects/predicate_signatures/src/main.sw new file mode 100644 index 0000000000..45da78449e --- /dev/null +++ b/packages/fuels/tests/test_projects/predicate_signatures/src/main.sw @@ -0,0 +1,35 @@ +predicate; + +use std::{ + tx::get_predicate_data, + ecr::ec_recover_address, + constants::ZERO_B256, + b512::B512, + result::* +}; + +fn extract_pulic_key_and_match(signature: B512, expected_public_key: b256) -> u64{ + if let Result::Ok(pub_key_sig) = ec_recover_address(signature, ZERO_B256) { + if pub_key_sig.value == expected_public_key{ + return 1; + } + } + 0 +} + +fn main() -> bool { + let signatures: [B512;3] = get_predicate_data(); + + let public_keys = [ + 0xd58573593432a30a800f97ad32f877425c223a9e427ab557aab5d5bb89156db0, + 0x14df7c7e4e662db31fe2763b1734a3d680e7b743516319a49baaa22b2032a857, + 0x3ff494fb136978c3125844625dad6baf6e87cdb1328c8a51f35bda5afe72425c]; + + let mut matched_keys = 0; + + matched_keys = extract_pulic_key_and_match(signatures[0], public_keys[0]); + matched_keys = matched_keys + extract_pulic_key_and_match(signatures[1], public_keys[1]); + matched_keys = matched_keys + extract_pulic_key_and_match(signatures[2], public_keys[2]); + + matched_keys > 1 +}