Auctions

A Pipoke auction is sealed-bid commit-reveal, second-price. Bidders publish a hash of (bid_amount, salt) during the commit window. They publish (bid_amount, salt) during the reveal window. The contract verifies the hash, ranks the revealed bids, and settles at the second-highest revealed price. Auctions live on PipokeAuctionRouter plus a fleet of shards: 16 public and 16 anonymous (32 shards total).

Pipoke runs on Octra Devnet today. Any fee, price, or limit referred to here is a contract setting chosen for testing. Every one is owner-settable, and mainnet values will be different. These docs describe how the mechanics work, not what the numbers are.

#The four item types

Item type	What it is	Adapter
Digital file	Any file you can upload: zip, jpg, png, mp3, mp4, pdf, txt, art, docs, sealed manuscript. Sealed into your Circle at create-time. The post-settle delivery hands the file (or its decrypt key) to the winner.	none
Biont NFT	A Biont Network biont. Deposited into the auction shard at create-time, transferred to the winner at settle-time.	`BIONT`
Other NFT / OCS token	Any XNS-1 or OCS-01 NFT or token id. Coin allocations, drop NFTs, badges, vouchers. Approved into the shard at create, transferred at settle.	`TOKEN`
RFP	A Request For Proposal. A sealed-bid contest on a topic. No item, no escrow item. Highest revealed bid wins. The opener picks the operator who settles. Used when the deliverable is defined by the topic itself, not a file or a token.	none

The first three pick which adapter the shard uses to verify ownership at create-time and to deliver at settle. RFPs run through their own modal flow (no adapter, no item ref).

#On-chain auction states

The shard tracks each auction as one of four states.

State	Number	Meaning
`ACTIVE`	0	The auction is live. Commit and reveal windows are open.
`SETTLED`	1	The auction settled. The item was delivered (or the RFP operator was selected).
`CANCELLED`	2	The seller cancelled before any reveal landed. Escrows refunded.
`AWAITING_DELIVERY`	3	The auction settled but the seller did not deliver inside the delivery window. The winner can call `claim_refund` and recover their bid `POKE`.

There is also an AUCTION_TYPE flag carried with each auction record: ENGLISH = 0 for open ascending price (rare, supports a different bidding flow), SEALED = 1 for the sealed-bid commit-reveal flow described here.

#Method surface

The four create paths land on the chosen shard:

create_auction(auction_type, item_ref, item_hash, min_bid_raw, duration_epochs, reveal_epochs) for digital files. item_ref is the oct:// URI in your Circle, item_hash binds it.
create_nft_auction(auction_type, adapter_kind, nft_contract, soul_ref, min_bid_raw, duration_epochs, reveal_epochs) for Biont NFTs. adapter_kind = BIONT (0).
create_token_auction(auction_type, adapter_kind, nft_contract, token_id, min_bid_raw, duration_epochs, reveal_epochs) for OCS-standard NFTs and tokens. adapter_kind = TOKEN (1).
open_rfp(...) opens the RFP. Different surface, separate vault contract.

Per-bid lifecycle methods on the shard:

commit_bid(local_id, commit_hash, deposit_raw) during the commit window. commit_hash = SHA-256(amount_raw || salt). deposit_raw covers the maximum you might pay.
reveal_bid(local_id, amount_raw, salt) during the reveal window. The shard verifies the hash against the commit.
bid(local_id, amount_raw) for ENGLISH auctions instead of commit_bid.
settle(local_id) (English) or settle_sealed(local_id) (sealed) at the end of the reveal window. Computes second-highest and pays.
deliver(local_id, blob) ships the digital file blob to the winner (for digital auctions).
confirm_receipt(local_id) the winner confirms delivery; the seller pulls the proceeds.
claim_no_delivery(local_id) the winner claims a refund after AWAITING_DELIVERY.
cancel_auction(local_id) the seller cancels before reveal lands.

For anonymous auctions, every method that takes a bidder identity uses your anon-bidder credential instead of your wallet. The shard exposes anon_bid_nonce_of(local_id, pubkey_b64) for replay protection per credential.

#Auction IDs

Global auction IDs encode the shard index in the upper bits.

global_id = shard_index * 2^48  +  local_id
local_id  = global_id  %  2^48
shard_idx = global_id  /  2^48

2^48 = 281474976710656. Given any global ID you can recover the shard and local ID in two integer ops, which is how the indexer routes a read back to the right shard.

#Allowance pattern

Before you bid you grant the shard a POKE allowance large enough to cover your maximum bid (plus the deposit). Pipoke uses the OCS-01 reset-first race-protection pattern: if your current allowance is non-zero and below the needed amount, the app resets it to zero and then grants the target value in a second transaction. See the POKE token.

#No-delivery refund

If the seller does not deliver after settlement (the item never lands on the winner's wallet inside the delivery window), the auction transitions to AWAITING_DELIVERY. The winner calls claim_refund (or claim_no_delivery) and the contract returns the bid POKE. The seller's deposit is forfeit to the protocol. This protects buyers in the digital-good case where delivery is the seller's responsibility.

#Public and anonymous shards

Shard set	Shards	Bidder identity
Public	16	Your wallet. The bid is signed with your main key. Anyone reading the chain can see who bid.
Anonymous	16	A separate anon-bidder credential. The seller never sees your wallet.

The anonymous variant uses the same anon-set commitment scheme as anonymous posting (a Groth16 BN254 proof over a Poseidon Merkle root of registered commitments). The seller still gets paid; they just never see who the buyer was. Multiple bids on the same auction from the same anon credential are linkable only through the per-auction anon_bid_nonce, which the seller cannot use to derive the underlying wallet.

#Action fees

Each phase (commit, reveal, settle, deliver, confirm_receipt) charges a small POKE fee. Fees route through PipokeFeeCollector with the standard split. Sellers also pay a listing fee on auction-create.

#Why sealed-bid second-price

Honest bidding. In a sealed-bid second-price auction, your optimal bid is your true valuation. You never overpay. You never have to game the price.

Sealed bids resist sniping. Commit-reveal hides your bid until the reveal window. A sniper cannot react to the price you set, because they cannot see it.

Two windows, not one. The commit window is when bids land. The reveal window is when bids resolve. If the reveal window is shorter than the commit window, last-second commit attempts are useless because they cannot reveal in time. The shard exposes both as auction-create parameters so the seller can tune the auction shape.