ic_auction/lib.rs
1//! Allocation mechanisms for scarce names and slots on the Internet
2//! Computer, as pure state machines the canister wraps.
3//!
4//! - [`harberger`]: a self-assessed price, a prepaid balance, tax settled
5//! lazily on every read and write, a grace period, then free. Anyone may
6//! buy at the assessed price at any time, which is what keeps the price
7//! honest.
8//! - [`vickrey`]: a sealed-bid second-price auction with commit and reveal
9//! phases, for allocating something that is free (a first sale, or a
10//! lapsed holding) to the bidder who values it most at the price the
11//! runner-up would have paid.
12//! - [`ledger`] (feature `icrc`): the ICRC-1/ICRC-2 client a canister
13//! uses to escrow and pay out in cycles or any ICRC token, with the
14//! failure classification that keeps a retry from paying twice.
15//!
16//! The mechanisms hold no money and make no calls. The canister owns the
17//! records and the escrow: it settles a [`harberger::Harberger`] and stores
18//! the result, escrows a deposit when it accepts a [`vickrey`] commitment
19//! and pays the [`vickrey::Outcome`] when it closes. Every rule is
20//! testable on the host. Amounts are in the caller's unit (cycles, or an
21//! ICRC token's smallest unit) and times are nanoseconds, as
22//! `ic_cdk::api::time()` returns them.
23//!
24//! # Harberger tax
25//!
26//! ```
27//! use ic_auction::harberger::{Harberger, Params, Status, YEAR_NS};
28//!
29//! let p = Params { rate_bps: 700, min_price: 1_000, grace_ns: 1_000_000_000 };
30//! let price = 1_000_000_000_000; // 1T cycles
31//! p.check_price(price).unwrap();
32//! // Take the item with a year of tax prepaid.
33//! let mut h = Harberger::new(price, p.tax_per_year(price), 0);
34//!
35//! // Settle on every read or write; count `taken` only when you store `h`.
36//! let (status, taken) = h.settle(&p, (YEAR_NS / 2) as u64);
37//! assert_eq!(status, Status::Active);
38//! assert_eq!(taken, p.tax_per_year(price) / 2);
39//!
40//! // A year and a millisecond in, the balance has run out (a holding
41//! // lapses once the tax owed exceeds it by a whole unit): grace, then free.
42//! let later = YEAR_NS as u64 + 1_000_000;
43//! let (status, _) = h.settle(&p, later);
44//! assert!(matches!(status, Status::Grace { .. }));
45//! assert_eq!(h.status(&p, later + p.grace_ns), Status::Free);
46//! ```
47//!
48//! # Vickrey auction
49//!
50//! ```
51//! use ic_auction::vickrey::{commitment, Auction, Params};
52//!
53//! let mut a = Auction::open(Params { commit_ns: 100, reveal_ns: 100, reserve: 10 }, 0);
54//! let (alice, bob) = (b"alice".to_vec(), b"bob".to_vec());
55//! // Salts are random and secret in practice; see `commitment`.
56//! let (sa, sb) = (b"16+ random bytes", b"more random byte");
57//!
58//! // Commit phase: a hash and an escrowed deposit each.
59//! a.commit(1, alice.clone(), commitment(&alice, 50, sa), 60).unwrap();
60//! a.commit(2, bob.clone(), commitment(&bob, 30, sb), 30).unwrap();
61//!
62//! // Reveal phase.
63//! a.reveal(150, &alice, 50, sa).unwrap();
64//! a.reveal(150, &bob, 30, sb).unwrap();
65//!
66//! // Closed: the highest bid wins at the second-highest.
67//! let o = a.outcome(200).unwrap();
68//! assert_eq!(o.winner, Some(alice.clone()));
69//! assert_eq!(o.price, 30);
70//! // Pay these out: alice gets 60 - 30 back, bob all 30.
71//! assert_eq!(o.settlements[0].refund, 30);
72//! assert_eq!(o.settlements[1].refund, 30);
73//! ```
74//!
75//! # Features
76//!
77//! - `candid`: derive `CandidType` on the public types, to store them in
78//! stable memory or return them from canister methods.
79//! - `icrc`: the [`ledger`] client. Pulls in `ic-cdk` and `candid`, so it
80//! is for use inside a canister.
81
82#![cfg_attr(docsrs, feature(doc_cfg))]
83#![warn(missing_docs)]
84
85pub mod harberger;
86pub mod vickrey;
87
88#[cfg(feature = "icrc")]
89#[cfg_attr(docsrs, doc(cfg(feature = "icrc")))]
90pub mod ledger;
91
92// The README's examples run as doctests, so they cannot drift.
93#[cfg(doctest)]
94#[doc = include_str!("../README.md")]
95struct ReadmeDoctests;