feat: add predicate example and docs (#541)

Co-authored-by: Ahmed Mujkic <[email protected]>

Cargo.toml

@@ -8,6 +8,7 @@ resolver = "2"
 members = [
     "examples/contracts",
     "examples/cookbook",
+    "examples/predicates",
     "examples/providers",
     "examples/rust_bindings",
     "examples/types",

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)

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.
+

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}}
+```

examples/predicates/Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "fuels-example-predicates"
+version = "0.0.0"
+edition = "2021"
+publish = false
+authors = ["Fuel Labs <[email protected]>"]
+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"] }

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::<Vec<_>>();
+
+        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(())
+    }
+}

packages/fuels-signers/src/provider.rs

@@ -570,7 +570,6 @@ impl Provider {
         tolerance: f64,
     ) -> Result<u64, ProviderError> {
         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)
     }
 

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,
         ))

packages/fuels/tests/test_projects/predicate_signatures/Forc.toml

@@ -0,0 +1,7 @@
+[project]
+authors = ["Fuel Labs <[email protected]>"]
+entry = "main.sw"
+license = "Apache-2.0"
+name = "predicate_signatures"
+
+[dependencies]

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
+}