ic-auction
Allocation mechanisms for scarce names and slots on the Internet Computer, as pure state machines a canister wraps.
- harberger: the holder self-assesses a price and prepays a balance; tax accrues on the price at a configured rate and settles lazily on every read and write; when the balance runs out a grace period starts, then the thing is free. Anyone may buy at the assessed price at any time, which is what keeps the price honest. No timers.
- vickrey: sealed-bid second-price auction. Bidders commit a hash of bidder, amount and salt with an escrowed deposit, reveal in the next phase, and the highest revealed bid wins at the second-highest price (or the reserve). Unrevealed commitments forfeit their deposit.
- ledger (feature
icrc): the ICRC-1/ICRC-2 client for escrow and payout in cycles or any ICRC token: pull under an approval, pay, fund the canister, read the fee.
The mechanisms hold no money and make no calls. The canister owns the records and the escrow, settles and stores, and pays out what an outcome says. Every rule is testable on the host.
Install
[]
= { = "0.1", = ["candid", "icrc"] }
| Feature | Adds |
|---|---|
| (none) | harberger and vickrey: pure Rust, serde and sha2 only |
candid |
CandidType on the public types, to store or return them |
icrc |
the ledger client; needs ic-cdk, so canister code only |
Minimum Rust: 1.88.
Example
use ;
let mut a = open;
let = ;
let = ;
a.commit.unwrap;
a.commit.unwrap;
a.reveal.unwrap;
a.reveal.unwrap;
let o = a.outcome.unwrap;
assert_eq!;
The crate docs have a Harberger example too, and every type and rule documented: https://docs.rs/ic-auction.
What the caller must get right
The crate keeps the rules; the canister keeps the money. These are the places the two meet.
- Count tax only when you store.
Harberger::settleandtop_upreturn the tax they took. Add it to your treasury only when you write the settled record back; a read that settles a copy takes nothing.settled_nsmay trailnowby under one unit's worth of time: that is the rounding carry, not a bug, so store it as returned. - Escrow before you commit, pay out after you close.
Auction::commitassumes the deposit is already held;Auction::outcomesays what each bidder is owed, and paying it is yours. A second commitment from the same bidder replaces the first, andcommitreturns the old deposit to refund. - Salts keep bids sealed. Amounts are few enough to try one by one against a published commitment, so bidders need at least 16 random bytes of salt, fresh for every bid, computed on their own machine (not by asking a canister, which would send it the bid).
- Validate auction phases. A zero-length reveal phase leaves nobody
time to reveal, and every commitment forfeits.
harberger::Paramshascheck; forvickrey::Paramscheck that both phases are positive. - Undo only what did not move.
ledger::Failure::nothing_movedis true only forRejectedandRefused.FeeCharged(a cycles-ledger withdraw that failed but kept its fee) means undo the amount but not the fee.Undecodablemeans the transfer may have happened: undo nothing, and record the amount for an operator to reconcile against the ledger's blocks, so a retry never pays twice. - Pinned fees. Every transfer pins the fee you pass, so a ledger fee
change makes the ledger refuse rather than debit more than you budgeted.
Read it with
ledger::feewhen you configure, and refresh on refusal.
Used by
ic-name-service: flat names held under the Harberger tax, sold by Vickrey auction when free, paid for in cycles. Sibling crates: ic-multisig (K-of-N approvals), ic-dev-kit-rs.
Development
The toolchain is pinned in rust-toolchain.toml. Source and docs are pure
ASCII. Changes are listed in CHANGELOG.md.
src/harberger.rs Params, Harberger, Status: tax, settle, top_up
src/vickrey.rs Params, Auction, Bid, Outcome: commit, reveal, outcome
src/ledger.rs pull, pay, fund_self, fee, Failure (feature icrc)
Releases are published from CI: bump version in Cargo.toml, add the
CHANGELOG entry, merge, then push a tag v<version>. The release workflow
checks the tag matches Cargo.toml, runs the checks, and publishes.
License
Licensed under either of Apache License, Version 2.0 or MIT license at your option. Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.