Send And Spend Funds From Predicates

Predicates can be used to validate transactions. This implies that a predicate can safeguard assets, only allowing their transfer if the predicate conditions are met.

This guide will demonstrate how to send and spend funds using a predicate.

Predicate Example

Consider the following predicate:

predicate;

fn main(input_address: b256) -> bool {
    let valid_address = 0xfc05c23a8f7f66222377170ddcbfea9c543dff0dd2d2ba4d0478a4521423a9d4;

    input_address == valid_address
}

See code in context

---

This predicate accepts an address of type b256 and compares it with a hard-coded address of the same type. If both addresses are equal, the predicate returns true, otherwise it will return false.

Interacting with the Predicate Using SDK

Let's use the above predicate to validate our transaction.

Once you've compiled the predicate (forc build), you'll obtain two important artifacts: the JSON ABI and the predicate's binary code. These are needed to instantiate a new predicate.

This is where we also pass in the predicate's data. Note that the main function in our predicate example requires a parameter called input_address of type b256. We will pass this parameter to the Predicate constructor along with the bytecode and the JSON ABI.

const inputAddress = '0xfc05c23a8f7f66222377170ddcbfea9c543dff0dd2d2ba4d0478a4521423a9d4';
const predicate = new Predicate({
  bytecode: bin,
  provider,
  abi,
  inputData: [inputAddress],
});

See code in context

---

Note: If you want to pass in the predicate data after instantiating the Predicate or if you want to use a different data than the one passed in the constructor, you will have to create a new Predicate instance.

With the predicate instantiated, we can transfer funds to its address. This requires us to have a wallet with sufficient funds. If you're unsure about using wallets with the SDK, we recommend checking out our wallet guide.

const amountToPredicate = 10_000;

const tx = await walletWithFunds.transfer(predicate.address, amountToPredicate, BaseAssetId, {
  gasPrice,
  gasLimit: 1_000,
});

await tx.waitForResult();

See code in context

---

Now that our predicate holds funds, we can use it to validate a transaction and hence execute our transfer. We can achieve that by doing the following:

const receiverWallet = WalletUnlocked.generate({
  provider,
});

const tx2 = await predicate.transfer(
  receiverWallet.address.toB256(),
  amountToPredicate - 1000,
  BaseAssetId,
  {
    gasPrice,
    gasLimit: 1_000,
  }
);

await tx2.waitForResult();

See code in context

---

Note the method transfer has two parameters: the recipient's address and the intended transfer amount.

Once the predicate resolves with a return value true based on its predefined condition, our predicate successfully spends its funds by means of a transfer to a desired wallet.

---

In a similar approach, you can use the createTransfer method, which returns a ScriptTransactionRequest. Then, we can submit this transaction request by calling the sendTransaction method.

This can be useful if you need the transaction ID before actually submitting it to the node.

const transactionRequest = await predicate.createTransfer(
  receiverWallet.address,
  amountToPredicate,
  BaseAssetId,
  {
    gasPrice,
    gasLimit: 1_000,
  }
);

const chainId = provider.getChainId();

const txId = transactionRequest.getTransactionId(chainId);

const res = await predicate.sendTransaction(transactionRequest);

await res.waitForResult();

See code in context

Spending Entire Predicate Held Amount

Trying to forward the entire amount held by the predicate results in an error because no funds are left to cover the transaction fees. Attempting this will result in an error message like:

const errorMsg = 'not enough coins to fit the target';

See code in context

Predicate Validation Failure

What happens when a predicate fails to validate? Recall our predicate only validates if the input_address matches the hard-coded valid_address. Hence, if we set a different data from the valid_address, the predicate will fail to validate.

When a predicate fails to validate, the SDK throws an error that starts like this:

const errorMsg = 'PredicateVerificationFailed';

See code in context

Pre-staging a Transaction

In some cases, you may want to pre-stage a predicate transaction before submitting it for execution. To do this, you can use the createTransfer method on the Predicate class.

In the following example, we are pre-staging a transaction to be able to know the transaction ID without actually submitting the transaction.

// Prepare the transaction
const preparedTx = await predicate.createTransfer(
  receiverWallet.address,
  amountToPredicate,
  BaseAssetId
);

// Get the transaction ID before sending the transaction
const txId = preparedTx.getTransactionId(provider.getChainId());

// Send the transaction
const res = await predicate.sendTransaction(preparedTx);
await res.waitForResult();

See code in context