Skip to content

Latest commit

 

History

History
462 lines (338 loc) · 17.6 KB

1.2_SDK_api_reference.md

File metadata and controls

462 lines (338 loc) · 17.6 KB

Aligned SDK

API Reference

submit

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

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

Arguments

  • batcher_url - The url of the batcher to which the proof will be submitted.
  • network - The network on which the proof will be submitted (devnet | holesky-stage | holesky)
  • 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(
    batcher_url: &str,
    network: Network,
    verification_data: &[VerificationData],
    max_fees: &[U256],
    wallet: Wallet<SigningKey>,
    nonce: U256,
) -> Result<Vec<AlignedVerificationData>, errors::SubmitError>

Arguments

  • batcher_url - The url of the batcher to which the proof will be submitted.
  • network - The network on which the proof will be submitted (devnet | holesky-stage | holesky)
  • verification_data - A verification data array.
  • max_fees - A max fee array.
  • 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.
  • 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.

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.
  • 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_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(
    batcher_url: &str,
    eth_rpc_url: &str,
    network: Network,
    verification_data: &VerificationData,
    max_fee: U256,
    wallet: Wallet<SigningKey>,
    nonce: U256,
) -> Result<AlignedVerificationData, errors::SubmitError>

Arguments

  • batcher_url - The url of the batcher to which the proof will be submitted.
  • eth_rpc_url - The URL of the Ethereum RPC node.
  • network - The network on which the verification will be done (devnet | holesky-stage | holesky)
  • 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.
  • payment_service_addr - The address of the batcher payment service contract.
  • 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.

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(
    batcher_url: &str,
    eth_rpc_url: &str,
    network: Network,
    verification_data: &[VerificationData],
    wallet: Wallet<SigningKey>,
    nonce: U256,
    payment_service_addr: &str,
) -> Vec<Result<AlignedVerificationData, errors::SubmitError>>

Arguments

  • batcher_url - The url of the batcher to which the proof will be submitted.
  • eth_rpc_url - The URL of the Ethereum RPC node.
  • network - The network on which the verification will be done (devnet | holesky-stage | holesky)
  • verification_data - A verification data array.
  • max_fees - A max fee array.
  • 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.
  • payment_service_addr - The address of the batcher payment service contract.
  • 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.

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,
    payment_service_addr: &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-stage | holesky)
  • eth_rpc_url - The URL of the Ethereum RPC node.
  • payment_service_addr - The address of the batcher payment service contract.

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_commitment

Generates a keccak256 hash commitment of the verification key.

pub fn get_commitment(
    content: &[u8]
) -> [u8; 32]

Arguments

  • content - A byte slice of the verification key.

Returns

  • [u8; 32] - A 32-byte array representing the keccak256 hash of the verification key.

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 address of the proof submitter for which the nonce will be retrieved.
  • network - The network on which the proof will be submitted

Returns

  • Result<U256, NonceError> - The nonce 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.
  • 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.

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(
    batcher_ws_url: &str,
    address: Address,
) -> Result<U256, GetNonceError> {

Arguments

  • batcher_url - The batcher websocket url.
  • 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. Wallet chain id needs to be set with:

wallet = wallet.with_chain_id(chain_id);

Arguments

  • eth_rpc_url - The URL of the Ethereum RPC node.

Returns

  • Result<U256, ChainIdError> - The nonce 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.

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,
    estimate: PriceEstimate,
) -> Result<U256, errors::MaxFeeEstimateError>

Arguments

  • eth_rpc_url - The URL of the Ethereum RPC node.
  • estimate - The parameter to set the priority for the proof to be included in the batch. It can be one of Min, Default or Max.

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.

compute_max_fee

Computes max_fee for a proof based on the number of proofs in a batch (num_proofs_per_batch) and number of proofs (num_proofs) in that batch the user would pay for i.e (num_proofs / num_proofs_per_batch).

pub async fn compute_max_fee(
    eth_rpc_url: &str,
    num_proofs: usize,
    num_proofs_per_batch: usize,
) -> Result<U256, errors::MaxFeeEstimateError>

Arguments

  • eth_rpc_url - The URL of the Ethereum RPC node.
  • num_proofs - The number of proofs in a batch the user would pay for.
  • num_proofs_per_batch - The number of proofs within a batch.

Returns

  • Result<U256, MaxFeeEstimateError> - The calculated max_fee as a U256.

Errors

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

fee_per_proof

Returns the fee_per_proof based on the current gas price for a batch compromised of num_proofs_per_batch i.e. (1 / num_proofs_per_batch).

pub async fn fee_per_proof(
    eth_rpc_url: &str,
    num_proofs_per_batch: usize,
) -> Result<U256, errors::MaxFeeEstimateError>

Arguments

  • eth_rpc_url - The URL of the users Ethereum RPC node.
  • num_proofs_per_batch - The number of proofs within a batch.

Returns

  • Result<U256, MaxFeeEstimateError> - The fee per proof of a batch of num_proofs_per_batch proofs as a U256.

Errors

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

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.