SDK API Reference

API Reference

submit

Submits a proof to the batcher to be verified and returns an aligned verification data struct.

pub async fn submit(
    network: Network,
    verification_data: &VerificationData,
    max_fee: U256,
    wallet: Wallet<SigningKey>,
    nonce: U256,
) -> Result<AlignedVerificationData, errors::SubmitError>

Arguments

• network - The network on which the proof will be submitted (devnet | holesky | mainnet)

• verification_data - The verification data for the proof.

• max_fee - The maximum fee that the submitter is willing to pay for the proof verification.

• wallet - The wallet used to sign the proof. Should be using correct chain id. See get_chain_id.

• nonce - The nonce of the submitter address. See get_nonce_from_ethereum.

Returns

• Result<AlignedVerificationData, SubmitError> - An aligned verification data or an error.

Errors

• MissingRequiredParameter if the verification data vector is empty.

• ProtocolVersionMismatch if the version of the SDK is lower than the expected one.

• UnexpectedBatcherResponse if the batcher doesn't respond with the expected message.

• SerializationError if there is an error deserializing the message sent from the batcher.

• WebSocketConnectionError if there is an error connecting to the batcher.

• WebSocketClosedUnexpectedlyError if the connection with the batcher is closed unexpectedly.

• InvalidSignature if the signature is invalid.

• InvalidNonce if the nonce is invalid.

• InvalidMaxFee if the max fee is invalid.

• InvalidProof if the proof is invalid.

• ProofTooLarge if the proof is too large.

• InsufficientBalance if the sender balance is not enough or unlocked

• ProofQueueFlushed if there is an error in the batcher and the proof queue is flushed.

• NotAContract(address) if you are trying to send to an address that is not a contract. This generally occurs if you have misconfigured the environment parameter.

• GenericError if the error doesn't match any of the previous ones.

submit_multiple

Submits multiple proofs to the batcher to be verified and returns an aligned verification data array.

pub async fn submit_multiple(
    network: Network,
    verification_data: &[VerificationData],
    max_fee: U256,
    wallet: Wallet<SigningKey>,
    nonce: U256,
) -> Result<Vec<AlignedVerificationData>, errors::SubmitError>

Arguments

• network - The network on which the proof will be submitted (devnet | holesky | mainnet)

• verification_data - A verification data array.

• max_fee - The maximum fee that the submitter is willing to pay for the verification for each proof.

• wallet - The wallet used to sign the proof. Should be using correct chain id. See get_chain_id.

• nonce - The nonce of the submitter address. See get_nonce_from_ethereum.

Returns

• Result<Vec<AlignedVerificationData>, SubmitError> - An aligned verification data array or an error.

Errors

• MissingRequiredParameter if the verification data vector is empty.

• ProtocolVersionMismatch if the version of the SDK is lower than the expected one.

• UnexpectedBatcherResponse if the batcher doesn't respond with the expected message.

• SerializationError if there is an error deserializing the message sent from the batcher.

• WebSocketConnectionError if there is an error connecting to the batcher.

• WebSocketClosedUnexpectedlyError if the connection with the batcher is closed unexpectedly.

• InvalidSignature if the signature is invalid.

• InvalidNonce if the nonce is invalid.

• InvalidMaxFee if the max fee is invalid.

• InvalidProof if the proof is invalid.

• ProofTooLarge if the proof is too large.

• InsufficientBalance if the sender balance is not enough or unlocked

• ProofQueueFlushed if there is an error in the batcher and the proof queue is flushed.

• GenericError if the error doesn't match any of the previous ones.

submit_and_wait_verification

Submits a proof to the batcher to be verified, waits for the verification on ethereum and returns an aligned verification data struct.

pub async fn submit_and_wait_verification(
    eth_rpc_url: &str,
    network: Network,
    verification_data: &VerificationData,
    max_fee: U256,
    wallet: Wallet<SigningKey>,
    nonce: U256,
) -> Result<AlignedVerificationData, errors::SubmitError>

Arguments

• eth_rpc_url - The URL of the Ethereum RPC node.

• network - The network on which the verification will be done (devnet | holesky | mainnet)

• verification_data - The verification data for the proof.

• max_fee - The maximum fee that the submitter is willing to pay for the proof verification.

• wallet - The wallet used to sign the proof. Should be using correct chain id. See get_chain_id.

• nonce - The nonce of the submitter address. See get_nonce_from_ethereum.

Returns

• Result<AlignedVerificationData, SubmitError> - An aligned verification data or an error.

Errors

• MissingRequiredParameter if the verification data vector is empty.

• ProtocolVersionMismatch if the version of the SDK is lower than the expected one.

• UnexpectedBatcherResponse if the batcher doesn't respond with the expected message.

• SerializationError if there is an error deserializing the message sent from the batcher.

• WebSocketConnectionError if there is an error connecting to the batcher.

• WebSocketClosedUnexpectedlyError if the connection with the batcher is closed unexpectedly.

• EthereumProviderError if there is an error in the connection with the RPC provider.

• HexDecodingError if there is an error decoding the Aligned service manager contract address.

• BatchVerificationTimeout if there is a timeout waiting for the batch verification.

• InvalidSignature if the signature is invalid.

• InvalidNonce if the nonce is invalid.

• InvalidMaxFee if the max fee is invalid.

• InvalidProof if the proof is invalid.

• ProofTooLarge if the proof is too large.

• InsufficientBalance if the sender balance is not enough or unlocked

• ProofQueueFlushed if there is an error in the batcher and the proof queue is flushed.

• NotAContract(address) if you are trying to send to an address that is not a contract. This generally occurs if you have misconfigured the environment parameter.

• GenericError if the error doesn't match any of the previous ones.

submit_multiple_and_wait_verification

Submits multiple proofs to the batcher for verification, waits for verification on Ethereum, and returns an array of Results containing aligned verification data that indicates whether each proof was successfully submitted. If a timeout occurs while waiting for verification, an additional Err is appended to the end of the returned array.

pub async fn submit_multiple_and_wait_verification(
    eth_rpc_url: &str,
    network: Network,
    verification_data: &[VerificationData],
    max_fee: U256,
    wallet: Wallet<SigningKey>,
    nonce: U256
) -> Vec<Result<AlignedVerificationData, errors::SubmitError>>

Arguments

• eth_rpc_url - The URL of the Ethereum RPC node.

• network - The network on which the verification will be done (devnet | holesky | mainnet)

• verification_data - A verification data array.

• max_fee - The maximum fee that the submitter is willing to pay for the proof verification.

• wallet - The wallet used to sign the proof. Should be using correct chain id. See get_chain_id.

• nonce - The nonce of the submitter address. See get_nonce_from_ethereum.

Returns

• Result<Vec<AlignedVerificationData>, SubmitError> - An aligned verification data array or an error.

Errors

• MissingRequiredParameter if the verification data vector is empty.

• ProtocolVersionMismatch if the version of the SDK is lower than the expected one.

• UnexpectedBatcherResponse if the batcher doesn't respond with the expected message.

• SerializationError if there is an error deserializing the message sent from the batcher.

• WebSocketConnectionError if there is an error connecting to the batcher.

• WebSocketClosedUnexpectedlyError if the connection with the batcher is closed unexpectedly.

• EthereumProviderError if there is an error in the connection with the RPC provider.

• HexDecodingError if there is an error decoding the Aligned service manager contract address.

• BatchVerificationTimeout if there is a timeout waiting for the batch verification.

• InvalidSignature if the signature is invalid.

• InvalidNonce if the nonce is invalid.

• InvalidMaxFee if the max fee is invalid.

• InvalidProof if the proof is invalid.

• ProofTooLarge if the proof is too large.

• InsufficientBalance if the sender balance is not enough or unlocked

• ProofQueueFlushed if there is an error in the batcher and the proof queue is flushed.

• NotAContract(address) if you are trying to send to an address that is not a contract. This generally occurs if you have misconfigured the environment parameter.

• GenericError if the error doesn't match any of the previous ones.

is_proof_verified

Checks if the proof has been verified with Aligned and is included in the batch on-chain.

pub async fn is_proof_verified(
    aligned_verification_data: AlignedVerificationData,
    network: Network,
    eth_rpc_url: &str
) -> Result<bool, errors::VerificationError>

Arguments

• aligned_verification_data - The aligned verification data obtained when submitting the proofs.

• network - The network on which the verification will be done (devnet | holesky | mainnet)

• eth_rpc_url - The URL of the Ethereum RPC node.

Returns

• Result<bool, VerificationError> - A boolean indicating whether the proof was verified on-chain and is included in the batch or an error.

Errors

• EthereumProviderError if there is an error in the connection with the RPC provider.

• EthereumCallError if there is an error in the Ethereum call.

• HexDecodingError if there is an error decoding the Aligned service manager contract address.

get_nonce_from_ethereum

Returns the nonce for a given address in Ethereum from aligned payment service contract. Note that it might be out of sync if you recently sent proofs. For that see get_nonce_from_batcher

pub async fn get_nonce_from_ethereum(
    eth_rpc_url: &str,
    submitter_addr: Address,
    network: Network,
) -> Result<U256, errors::NonceError>

Arguments

• eth_rpc_url - The URL of the Ethereum RPC node.

• submitter_addr - The user address for which the nonce will be retrieved.

• network - The network from which the nonce will be retrieved.

Returns

• Result<U256, NonceError> - The nonce to use or an error.

Errors

• EthRpcError if the batcher has an error in the Ethereum call when retrieving the nonce if not already cached.

get_nonce_from_batcher

Returns the next nonce for a given address from the batcher.

You should prefer this method instead of get_nonce_from_ethereum if you have recently sent proofs, as the batcher proofs might not yet be on ethereum, producing an out-of-sync nonce with the payment service contract on ethereum

pub async fn get_nonce_from_batcher(
    network: Network,
    address: Address,
) -> Result<U256, GetNonceError> {

Arguments

• network - The network from which the nonce will be retrieved.

• address - The user address for which the nonce will be retrieved.

Returns

• Result<U256, NonceError> - The next nonce of the proof submitter account.

Errors

• EthRpcError if the batcher has an error in the Ethereum call when retrieving the nonce if not already cached.

get_chain_id

Returns the chain ID for a given rpc url.

Should be used before submitting proofs to the batcher.

pub async fn get_chain_id(
  eth_rpc_url: &str
) -> Result<u64, errors::ChainIdError>

Arguments

• eth_rpc_url - The URL of the Ethereum RPC node.

Returns

• Result<u64, ChainIdError> - The chain ID to use or an error.

Errors

• EthereumProviderError if there is an error in the connection with the RPC provider.

• EthereumCallError if there is an error in the Ethereum call.

Wallet chain ID needs to be set with:

wallet = wallet.with_chain_id(chain_id);

estimate_fee

Estimates the fee the user would have to pay for submitting a proof to Aligned. Depending on the priority the user wants to have in the batch, the estimate parameter can be set.

pub async fn estimate_fee(
    eth_rpc_url: &str,
    fee_estimation_type: FeeEstimationType,
) -> Result<U256, errors::MaxFeeEstimateError>

Arguments

• eth_rpc_url - The URL of the Ethereum RPC node.

• fee_estimation_type - Enum specifying the type of price estimate: Default, Instant. Custom(usize)

Returns

• Result<U256, MaxFeeEstimateError> - the estimated max_fee depending on the batch inclusion preference of the user.

Errors

• EthereumProviderError if there is an error in the connection with the RPC provider.

• EthereumCallError if there is an error in the Ethereum call.

calculate_fee_per_proof_for_batch_of_size

Returns the fee_per_proof based on the current gas price for a batch compromised of num_proofs_per_batch

pub async fn calculate_fee_per_proof_for_batch_of_size(
    eth_rpc_url: &str,
    num_proofs_in_batch: usize,
) -> Result<U256, errors::FeeEstimateError>

Arguments

• eth_rpc_url - The URL of the users Ethereum RPC node.

• num_proofs_in_batch - number of proofs within a batch.

Returns

• Result<U256, errors::FeeEstimateError> - The fee per proof of a batch as a U256.

Errors

-EthereumProviderError if there is an error in the connection with the RPC provider. -EthereumGasPriceError if there is an error retrieving the Ethereum gas price.

deposit_to_aligned

Funds the batcher payment service in name of the signer.

pub async fn deposit_to_aligned(
    amount: U256,
    signer: SignerMiddleware<Provider<Http>, LocalWallet>,
    network: Network,
) -> Result<ethers::types::TransactionReceipt, errors::PaymentError> {

Arguments

amount - The amount to be paid.signer - The signer middleware of the payer.network - The network on which the payment will be done.

Returns

The receipt of the payment transaction.

Errors

SendError if there is an error sending the transaction.SubmitError if there is an error submitting the transaction.PaymentFailed if the payment failed.

get_balance_in_aligned

Queries a User's balance that was deposited in Aligned

pub async fn get_balance_in_aligned(
    user: Address,
    eth_rpc_url: &str,
    network: Network,
) -> Result<U256, errors::BalanceError> {

Arguments

user - The address of the user.eth_rpc_url - The URL of the Ethereum RPC node.network - The network on which the balance will be checked.

Returns

• Result<U256, errors::BalanceError> - The balance of the user in the payment service.

Errors

• EthereumProviderError if there is an error in the connection with the RPC provider.

• EthereumCallError if there is an error in the Ethereum call.

get_vk_commitment

Returns the commitment for the verification key, taking into account the corresponding proving system.

pub fn get_vk_commitment(
    verification_key_bytes: &[u8],
    proving_system: ProvingSystemId,
) -> [u8; 32]

Arguments

• verification_key_bytes - The serialized contents of the verification key.

• proving_system - The corresponding proving system ID.

Returns

• [u8; 32] - The commitment.

Errors

• None.

save_response

Saves AlignedVerificationData in a file.

pub fn save_response(
    batch_inclusion_data_directory_path: PathBuf,
    aligned_verification_data: &AlignedVerificationData,
) -> Result<(), errors::FileError>

Arguments

-batch_inclusion_data_directory_path - The path of the directory where the data will be saved. -aligned_verification_data - The aligned verification data to be saved.

Returns

• Result<(), errors::FileError> - Ok if the data is saved successfully.

Errors

• FileError if there is an error writing the data to the file.