The Auction program can be used to create inference job requests to be auctioned in bundles, place/reveal bids on an auction, submit the output of running a job request, and submit the validation result ran on job request outputs. source code: https://github.com/ambient-xyz/auction-api

Getting Started

From your project folder:

cargo add ambient-auction-api --git <https://github.com/ambient-xyz/auction-api>

This will add the ambient-auction-api to your Cargo.toml file. This crate contains the account and data structures expected by each of the instructions of the ambient auction program.

State

`JobRequest`

Account created and owned by the auction program to keep state related to a user inference request.

pub struct JobRequest {
    /// The public key of the bundle this request is participating in
    pub bundle: Pubkey,
    /// The maximum price per output token
    pub max_price_per_output_token: u64,
    /// The maximum output token this request accepts
    pub max_output_tokens: u64,
    /// Context length tier type
    pub context_length_tier: RequestTier,
    /// Expiry duration tier type
    pub expiry_duration_tier: RequestTier,
    /// The public key of the job requester.
    pub authority: Pubkey,
    /// An [IPFS content identifier](<https://docs.ipfs.tech/concepts/content-addressing/>) of the metadata necessary to complete the job.
    pub input_hash: Pubkey,
    pub input_hash_iv: [u8; 16],
    /// seeds used to derive the request PDA
    pub seed: [u8; 32],
    /// bump for the request account
    pub bump: u64,
    /// Output tokens generated
    pub output_token_count: u64,
    /// Request input tokens
    pub input_token_count: u64,
		/// Current lifecycle stage of the job request.
		/// 
		/// Indicates whether the request is still awaiting inference,
		/// pending verification, or already completed.
    pub status: JobRequestStatus,
		/// Verification-related state for this job request.
		/// 
		/// Tracks verifier assignments, token ranges, hashes, and progress
		/// through the verification process.
    pub verification: VerificationState,
    /// account used to store the input data for the inference job request
    pub input_data_account: Option<NonZeroPubkey>,
    /// account used to store the output data for the inference job request
    pub output_data_account: Option<NonZeroPubkey>,
}

/// Represents the lifecycle status of a job request.
pub enum JobRequestStatus {
    /// The request has been created and is waiting for inference output.
    WaitingForOutput = 0,
    /// The inference output has been generated and is awaiting verification.
    OutputReceived = 1,
    /// The output has been verified and the request is completed.
    OutputVerified = 2,
}

/// Holds all data required to manage and track verification of a job request.
/// 
/// Includes:
/// - Merkle root of the job’s output data.
/// - Assigned verifiers and their corresponding token ranges.
/// - Individual verifier states and verified token counts.
/// - Output hash for integrity checks (optionally encrypted).
/// - Initialization vectors (IVs) for optional encryption of the output hash
///   and Merkle root, using a shared secret between client and ambient.
pub struct VerificationState {
    pub merkle_root: [u8; 32],
    pub assigned_verifiers: [Pubkey; VERIFIERS_PER_AUCTION],
    pub assigned_verifiers_token_ranges: [u64; VERIFIERS_PER_AUCTION * 2],
    pub verifier_states: [JobVerificationState; VERIFIERS_PER_AUCTION],
    pub verified_tokens: [u64; VERIFIERS_PER_AUCTION],
    pub output_hash: [u8; 32],
    /// output hash and merkle root may be encrypted with a shared secret + iv,
    /// where shared_secret = ambient private key x client public key
    /// and IV is a random byte array (a nonce in crypto terms)
    ///
    /// encryption is used iff `encryption_iv` != [0; 16]
    pub output_hash_iv: [u8; 16],
    pub merkle_root_iv: [u8; 16],
}

NOTE: more on RequestTier in the RequestBundle section.

`RequestBundle`

Economically similar requests are bundled together. Request similarity is based on their context length and expiry duration RequestTier. Each (context length, expiry duration) pair has an associated “bundle chain” (explained later).

Once a bundle is concluded (marked as BundleStatus::Cancelled or BundleStatus::Filled), a new child bundle with an identical (context length, expiry duration) pair is created from it.

pub struct RequestBundle {
    /// Current status of the bundle
    pub status: BundleStatus,
    /// Context length tier type
    pub context_length_tier: RequestTier,
    /// Expiry duration tier type
    pub expiry_duration_tier: RequestTier,
    /// The auction for this bundle.
    pub auction: Option<NonZeroPubkey>,
    /// Assigned verifiers for this bundle.
    pub verifiers: Verifiers,
    /// The slot after which the auction cannot receive any more bids 
    /// and is considered ended.
    pub expiry_slot: u64,
    /// The maximum input tokens each request can have
    pub max_context_length: u64,
    /// Total number of requests contained in this bundle.
    pub requests_len: u64,
    /// The number of job requests that were successfully verified
    pub num_verified_requests: u64,
    /// limit how much time winning bidder can take to submit all jobs
    pub job_submission_duration: u64,
    /// Total amount commited by the requesters
    pub request_committed_amount: u64,
    /// Total input tokens in the requests
    pub total_input_tokens: u64,
    /// Maximum output tokens to be generated for the requests
    pub maximum_output_tokens: u64,
    /// Total output tokens generated for the requests
    pub output_tokens_generated: u64,
    /// the parent bundle key is bundle is derived from
    pub parent_bundle_key: Pubkey,
    /// The child bundle key to be derived from this bundle
    pub child_bundle_key: Option<NonZeroPubkey>,
    /// bump for this bundle account
    pub bump: u64,
    /// payer key for the bundle account creation
    pub payer: Pubkey,
    /// The clearing price from the concluded auction for this bundle.
    /// Denotes the payment rate (in lamports) per output token that the
    /// winning bidder will receive for fulfilling the bundle’s requests.
    pub price_per_output_token: Option<NonZeroU64>,
}

`Auction`

A bundle is put up for auction once it is created. The auction follows a second-lowest reverse auction: instead of the lowest bid winning, the second-lowest bidder is selected.

The winning bidder must execute every inference request in the bundle and submit the results. These outputs are then verified by a set of randomly assigned verifiers, selected proportionally to their network contribution (i.e. Lstake amount).

pub struct Auction {
    /// Context length tier type
    pub context_length_tier: RequestTier,
    /// Expiry duration tier type
    pub expiry_duration_tier: RequestTier,
    /// Bundle of requests for this auction.
    pub request_bundle: Pubkey,
    /// The slot after which the auction cannot receive any more bids
    /// and is considered ended.
    pub expiry_slot: u64,
    /// The maximum input tokens each request can have
    pub max_context_length: u64,
    /// The lowest bid price submitted
    pub lowest_bid_price: Option<NonZeroU64>,
    /// The second-lowest bid price submitted
    pub winning_bid_price: Option<NonZeroU64>,
    /// The public key of the winning bid account
    pub winning_bid: Pubkey,
    /// The public key of the lowest priced bid account
    pub lowest_bid: Pubkey,
    /// Current status of the auction
    pub status: AuctionStatus,
    /// Total number of bids revealed
    pub bids_revealed: u64,
    /// Total number of concealed bids placed
    pub bids_placed: u64,
    /// Amount to be kept in each bid account as commitment,
    pub bid_commitment_amount: u64,
    /// bump for this auction account
    pub auction_bump: u64,
    /// The fee payer for creating this account
    pub payer: Pubkey,
}

Getting Started

State

JobRequest

RequestBundle

Auction

BundleRegistry

`JobRequest`

`RequestBundle`

`Auction`

`BundleRegistry`