Struct CallBuilder 

pub struct CallBuilder<P, D, N = Ethereum>
where
    N: Network,
{
    pub provider: P,
    /* private fields */
}

Available on crate feature contract only.

A builder for sending a transaction via eth_sendTransaction, or calling a contract via eth_call.

The builder can be .awaited directly, which is equivalent to invoking call. Prefer using call when possible, as awaiting the builder directly will consume it, and currently also boxes the future due to type system limitations.

A call builder can currently be instantiated in the following ways:

• by sol!-generated contract structs’ methods (through the #[sol(rpc)] attribute) (SolCallBuilder);
• by ContractInstance’s methods (DynCallBuilder);
• using CallBuilder::new_raw (RawCallBuilder).

Each method represents a different way to decode the output of the contract call.

Note

This will set state overrides for eth_call, but this is not supported by all clients.

Examples

Using sol!:

use alloy_contract::SolCallBuilder;
use alloy_primitives::{Address, U256};
use alloy_sol_types::sol;

sol! {
    #[sol(rpc)] // <-- Important!
    contract MyContract {
        function doStuff(uint a, bool b) public returns(address c, bytes32 d);
    }
}

let provider = ...;
let address = Address::ZERO;
let contract = MyContract::new(address, &provider);

// Through `contract.<function_name>(args...)`
let a = U256::ZERO;
let b = true;
let builder: SolCallBuilder<_, MyContract::doStuffCall, _> = contract.doStuff(a, b);
let MyContract::doStuffReturn { c: _, d: _ } = builder.call().await?;

// Through `contract.call_builder(&<FunctionCall { args... }>)`:
// (note that this is discouraged because it's inherently less type-safe)
let call = MyContract::doStuffCall { a, b };
let builder: SolCallBuilder<_, MyContract::doStuffCall, _> = contract.call_builder(&call);
let MyContract::doStuffReturn { c: _, d: _ } = builder.call().await?;

Using ContractInstance:

use alloy_primitives::{Address, Bytes, U256};
use alloy_dyn_abi::DynSolValue;
use alloy_contract::{CallBuilder, ContractInstance, DynCallBuilder, Interface, RawCallBuilder};

let dynamic_abi: JsonAbi = ...;
let interface = Interface::new(dynamic_abi);

let provider = ...;
let address = Address::ZERO;
let contract: ContractInstance<_, _> = interface.connect(address, &provider);

// Build and call the function:
let call_builder: DynCallBuilder<_, _> = contract.function("doStuff", &[U256::ZERO.into(), true.into()])?;
let result: Vec<DynSolValue> = call_builder.call().await?;

// You can also decode the output manually. Get the raw bytes:
let raw_result: Bytes = call_builder.call_raw().await?;
// Or, equivalently:
let raw_builder: RawCallBuilder<_, _> = call_builder.clone().clear_decoder();
let raw_result: Bytes = raw_builder.call().await?;
// Decode the raw bytes:
let decoded_result: Vec<DynSolValue> = call_builder.decode_output(raw_result)?;

Fields

provider: P

The provider.

Implementations

impl<P, D, N> CallBuilder<P, D, N>

where N: Network,

pub fn into_transaction_request(self) -> <N as Network>::TransactionRequest

Converts the call builder to the inner transaction request

pub fn build_unsigned_raw_transaction( self, ) -> Result<Vec<u8>, TransactionBuilderError<N>>

where <N as Network>::UnsignedTx: SignableTransaction<Signature>,

Builds and returns a RLP-encoded unsigned transaction from the call that can be signed.

Examples

sol! {
    #[sol(rpc, bytecode = "0x")]
   contract Counter {
       uint128 public counter;

       function increment() external {
           counter += 1;
       }
   }
}

#[tokio::main]
async fn main() {
    let provider = ProviderBuilder::new().connect_anvil_with_wallet();

    let my_contract = Counter::deploy(provider).await.unwrap();

    let call = my_contract.increment();

    let unsigned_raw_tx: Vec<u8> = call.build_unsigned_raw_transaction().unwrap();

    assert!(!unsigned_raw_tx.is_empty())
}

pub async fn build_raw_transaction<S>( self, signer: S, ) -> Result<Vec<u8>, TransactionBuilderError<N>>

where S: TxSigner<Signature> + IntoWallet<N>,

Build a RLP-encoded signed raw transaction for the call that can be sent to the network using Provider::send_raw_transaction.

Examples

sol! {
   #[sol(rpc, bytecode = "0x")]
  contract Counter {
     uint128 public counter;

    function increment() external {
       counter += 1;
   }
 }
}

#[tokio::main]
async fn main() {
    let provider = ProviderBuilder::new().connect_anvil_with_wallet();

    let my_contract = Counter::deploy(&provider).await.unwrap();

    let call = my_contract.increment();

    let pk_signer: PrivateKeySigner = "0x..".parse().unwrap();
    let signed_raw_tx: Vec<u8> = call.build_raw_transaction(pk_signer).await.unwrap();

    let tx = provider.send_raw_transaction(&signed_raw_tx).await.unwrap();
}

impl<P, D, N> CallBuilder<P, D, N>

where P: Provider<N>, N: Network,

pub fn clear_decoder(self) -> CallBuilder<P, (), N>

Clears the decoder, returning a raw call builder.

impl<P, N> CallBuilder<P, (), N>

where P: Provider<N>, N: Network,

pub fn with_sol_decoder<C>(self) -> CallBuilder<P, PhantomData<C>, N>

where C: SolCall,

Sets the decoder to the provided SolCall.

Converts the raw call builder into a sol call builder.

Note that generally you would want to instantiate a sol call builder directly using the sol! macro, but this method is provided for flexibility, for example to convert a raw deploy call builder into a sol call builder.

Examples

Decode a return value from a constructor:

sol! {
    // NOTE: This contract is not meant to be deployed on-chain, but rather
    // used in a static call with its creation code as the call data.
    #[sol(rpc, bytecode = "34601457602a60e052600161010052604060e0f35b5f80fdfe")]
    contract MyContract {
        // The type returned by the constructor.
        #[derive(Debug, PartialEq)]
        struct MyStruct {
            uint64 a;
            bool b;
        }

        constructor() {
            MyStruct memory s = MyStruct(42, true);
            bytes memory returnData = abi.encode(s);
            assembly {
                return(add(returnData, 0x20), mload(returnData))
            }
        }

        // A shim that represents the return value of the constructor.
        function constructorReturn() external view returns (MyStruct memory s);
    }
}

let provider = ...;
let call_builder = MyContract::deploy_builder(&provider)
    .with_sol_decoder::<MyContract::constructorReturnCall>();
let result = call_builder.call().await?;
assert_eq!(result, MyContract::MyStruct { a: 42, b: true });

impl<P, N> CallBuilder<P, (), N>

where P: Provider<N>, N: Network,

pub fn new_raw(provider: P, input: Bytes) -> CallBuilder<P, (), N>

Creates a new call builder with the provided provider and ABI encoded input.

Will not decode the output of the call, meaning that call will behave the same as call_raw.

pub fn new_raw_deploy(provider: P, input: Bytes) -> CallBuilder<P, (), N>

Creates a new call builder with the provided provider and contract deploy code.

Will not decode the output of the call, meaning that call will behave the same as call_raw.

impl<P, D, N> CallBuilder<P, D, N>

where P: Provider<N>, D: CallDecoder, N: Network,

pub fn chain_id(self, chain_id: u64) -> CallBuilder<P, D, N>

Sets the chain_id field in the transaction to the provided value

pub fn from(self, from: Address) -> CallBuilder<P, D, N>

Sets the from field in the transaction to the provided value.

pub fn kind(self, to: TxKind) -> CallBuilder<P, D, N>

Sets the transaction request to the provided tx kind.

pub fn to(self, to: Address) -> CallBuilder<P, D, N>

Sets the to field in the transaction to the provided address.

pub fn sidecar( self, blob_sidecar: BlobTransactionSidecar, ) -> CallBuilder<P, D, N>

where <N as Network>::TransactionRequest: TransactionBuilder4844,

Sets the sidecar field in the transaction to the provided value.

pub fn sidecar_7594( self, sidecar: BlobTransactionSidecarEip7594, ) -> CallBuilder<P, D, N>

where <N as Network>::TransactionRequest: TransactionBuilder4844,

Sets the EIP-7594 sidecar field in the transaction to the provided value.

pub fn gas(self, gas: u64) -> CallBuilder<P, D, N>

Sets the gas field in the transaction to the provided value

pub fn gas_price(self, gas_price: u128) -> CallBuilder<P, D, N>

Sets the gas_price field in the transaction to the provided value If the internal transaction is an EIP-1559 one, then it sets both max_fee_per_gas and max_priority_fee_per_gas to the same value

pub fn max_fee_per_gas(self, max_fee_per_gas: u128) -> CallBuilder<P, D, N>

Sets the max_fee_per_gas in the transaction to the provide value

pub fn max_priority_fee_per_gas( self, max_priority_fee_per_gas: u128, ) -> CallBuilder<P, D, N>

Sets the max_priority_fee_per_gas in the transaction to the provide value

pub fn max_fee_per_blob_gas( self, max_fee_per_blob_gas: u128, ) -> CallBuilder<P, D, N>

where <N as Network>::TransactionRequest: TransactionBuilder4844,

Sets the max_fee_per_blob_gas in the transaction to the provided value

pub fn access_list(self, access_list: AccessList) -> CallBuilder<P, D, N>

Sets the access_list in the transaction to the provided value

pub fn authorization_list( self, authorization_list: Vec<SignedAuthorization>, ) -> CallBuilder<P, D, N>

where <N as Network>::TransactionRequest: TransactionBuilder7702,

Sets the authorization_list in the transaction to the provided value

pub fn value(self, value: Uint<256, 4>) -> CallBuilder<P, D, N>

Sets the value field in the transaction to the provided value

pub fn nonce(self, nonce: u64) -> CallBuilder<P, D, N>

Sets the nonce field in the transaction to the provided value

pub fn map<F>(self, f: F) -> CallBuilder<P, D, N>

where F: FnOnce(<N as Network>::TransactionRequest) -> <N as Network>::TransactionRequest,

Applies a function to the internal transaction request.

pub const fn block(self, block: BlockId) -> CallBuilder<P, D, N>

Sets the block field for sending the tx to the chain

pub fn state( self, state: impl Into<HashMap<Address, AccountOverride, FbBuildHasher<20>>>, ) -> CallBuilder<P, D, N>

Sets the state override set.

Note

Not all client implementations will support this as a parameter to eth_call.

pub fn calldata(&self) -> &Bytes

Returns the underlying transaction’s ABI-encoded data.

pub async fn estimate_gas(&self) -> Result<u64, Error>

Returns the estimated gas cost for the underlying transaction to be executed If state overrides are set, they will be applied to the gas estimation.

pub fn call(&self) -> EthCall<'_, D, N>

Queries the blockchain via an eth_call without submitting a transaction to the network. If state overrides are set, they will be applied to the call.

Returns the decoded the output by using the provided decoder. If this is not desired, use call_raw to get the raw output data.

pub fn call_raw(&self) -> EthCall<'_, (), N>

Queries the blockchain via an eth_call without submitting a transaction to the network. If state overrides are set, they will be applied to the call.

Does not decode the output of the call, returning the raw output data instead.

See call for more information.

pub fn decode_output( &self, data: Bytes, ) -> Result<<D as CallDecoder>::CallOutput, Error>

Decodes the output of a contract function using the provided decoder.

pub async fn deploy(&self) -> Result<Address, Error>

Broadcasts the underlying transaction to the network as a deployment transaction, returning the address of the deployed contract after the transaction has been confirmed.

Returns an error if the transaction is not a deployment transaction, or if the contract address is not found in the deployment transaction’s receipt.

For more fine-grained control over the deployment process, use send instead.

Note that the deployment address can be pre-calculated if the from address and nonce are known using calculate_create_address.

pub async fn deploy_sync(&self) -> Result<Address, Error>

Broadcasts the underlying transaction to the network as a deployment transaction and waits for the receipt, returning the address of the deployed contract.

This uses eth_sendRawTransactionSync (EIP-7966), which returns the transaction receipt in the same request rather than just the transaction hash.

Returns an error if the transaction is not a deployment transaction, or if the contract address is not found in the deployment transaction’s receipt.

For more fine-grained control over the deployment process, use deploy instead.

Note that the deployment address can be pre-calculated if the from address and nonce are known using calculate_create_address.

Note

Not all providers and clients support eth_sendRawTransactionSync yet.

pub async fn send(&self) -> Result<PendingTransactionBuilder<N>, Error>

Broadcasts the underlying transaction to the network.

Returns a builder for configuring the pending transaction watcher. See Provider::send_transaction for more information.

pub async fn send_sync(&self) -> Result<<N as Network>::ReceiptResponse, Error>

Broadcasts the underlying transaction to the network and waits for the receipt.

This uses eth_sendRawTransactionSync (EIP-7966), which returns the transaction receipt in the same request rather than just the transaction hash.

Returns the transaction receipt if the transaction was confirmed.

See Provider::send_transaction_sync for more information.

Note

Not all providers and clients support eth_sendRawTransactionSync yet.

pub fn calculate_create_address(&self) -> Option<Address>

Calculates the address that will be created by the transaction, if any.

Returns None if the transaction is not a contract creation (the to field is set), or if the from or nonce fields are not set.

impl<P, D, N> CallBuilder<&P, D, N>

where P: Clone, N: Network,

pub fn with_cloned_provider(self) -> CallBuilder<P, D, N>

Clones the provider and returns a new builder with the cloned provider.

Trait Implementations

impl<P, D, N> AsRef<<N as Network>::TransactionRequest> for CallBuilder<P, D, N>

where N: Network,

fn as_ref(&self) -> &<N as Network>::TransactionRequest

Converts this type into a shared reference of the (usually inferred) input type.

impl<P, D, N> Clone for CallBuilder<P, D, N>

where P: Clone, D: Clone, N: Clone + Network, <N as Network>::TransactionRequest: Clone,

fn clone(&self) -> CallBuilder<P, D, N>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<P, D, N> Debug for CallBuilder<P, D, N>

where D: CallDecoder, N: Network,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<P, C, N> MulticallItem for CallBuilder<P, PhantomData<C>, N>

where P: Provider<N>, C: SolCall, N: Network,

type Decoder = C

Decoder for the return data of the call.

fn value(&self) -> Uint<256, 4>

Returns the value to send with the call.

fn target(&self) -> Address

The target address of the call.

fn input(&self) -> Bytes

ABI-encoded input data for the call.

fn into_call(self, allow_failure: bool) -> CallItem<Self::Decoder>

where Self: Sized,

Converts self to a CallItem while specifying whether it can fail.

Layout

Note: Unable to compute type layout, possibly due to this type having generic parameters. Layout can only be computed for concrete, fully-instantiated types.