From 8b45443b7d4850016e09c30aca712a14571f9343 Mon Sep 17 00:00:00 2001 From: Chase Date: Thu, 15 Oct 2026 18:00:12 +0100 Subject: [PATCH] docs: rustdoc for receipt-shard's exported names and the buyback event fields (#749, #790) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `contracts/receipt-shard/src/lib.rs`'s four public names and the five public fields of `BuybackConfiguredEvent` shipped with no doc comment: `missing_docs` is not enabled workspace-wide and no CI step runs `cargo doc`, so the surface an integrating caller reads first had no statement of what a key holds, which arm returns which error, or who writes an event field. Document only the lines named by #749 and #790 - role for the enum and the contract struct, pre-condition and per-arm error for `get_batch` and `extend_batch_ttl`, unit/domain and writer for each event field. Comments only: no signature, layout, ordering or behaviour change. ROADMAP.md records both, and a doc-only CHANGELOG entry keeps the `changelog & version check` gate green. 🤖 Generated with Codebuff Co-Authored-By: Codebuff --- CHANGELOG.md | 3 +++ ROADMAP.md | 12 +++++++++++- contracts/receipt-shard/src/lib.rs | 12 ++++++++++++ contracts/treasury/src/buyback.rs | 10 ++++++++++ 4 files changed, 36 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a517edcb..d3650fe3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,9 @@ breaking changes bump the **minor** version, and they are called out as such. accepts an optional `coupon_id` parameter; when provided, the discount is applied atomically before the token transfer. Added error codes `CouponNotFound` and `CouponAlreadyRedeemed` to the common Error enum. +- docs: rustdoc for `receipt-shard`'s 4 exported names (#749) and for the 5 + public fields of `BuybackConfiguredEvent` (#790). Doc comments only — no + signature, struct layout or behaviour change. ### Added - **`privacy` (issue #440): Groth16 verification for concealed escrow amounts.** diff --git a/ROADMAP.md b/ROADMAP.md index 5e206ee8..c9ab2d3e 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -6,4 +6,14 @@ - New `liquid_staking` module in `contracts/governance/src/liquid_staking.rs` - 1:1 mint/burn of stACC against locked underlying tokens - Exchange rate progression and lock-epoch-based redemption - - CHANGELOG.md entry added \ No newline at end of file + - CHANGELOG.md entry added + +## Issue #749: rustdoc for receipt-shard's 4 exported names + +- [x] Document `DataKey`, `ReceiptShard`, `get_batch` and `extend_batch_ttl` (#749) + - `contracts/receipt-shard/src/lib.rs` — doc comments only, no signature, body or test changes + +## Issue #790: rustdoc for `BuybackConfiguredEvent`'s 5 public fields + +- [x] Document the struct's 5 public fields (#790) + - `contracts/treasury/src/buyback.rs` — doc comments only, field/type/order/derives unchanged diff --git a/contracts/receipt-shard/src/lib.rs b/contracts/receipt-shard/src/lib.rs index 607f6cba..990e3c84 100644 --- a/contracts/receipt-shard/src/lib.rs +++ b/contracts/receipt-shard/src/lib.rs @@ -21,6 +21,7 @@ contractmeta!( ); contractmeta!(key = "commit", val = env!("GIT_SHA")); +/// Storage keys for this shard's instance state and its per-batch records. #[contracttype] pub enum DataKey { Router, @@ -66,6 +67,9 @@ const TTL_THRESHOLD: u32 = 100; /// MAX_BATCH_SIZE = 1000 (router constant), that is 10. const MAX_PROOF_LEN: u32 = 10; +/// A storage shard: holds the batch records for one `[start_batch_id, +/// end_batch_id)` slice of a router's batch stream. Every state-changing +/// entry point authenticates the `router` address recorded at construction. #[contract] pub struct ReceiptShard; @@ -140,6 +144,10 @@ impl ReceiptShard { .extend_ttl(&DataKey::Batch(batch_id), TTL_THRESHOLD, TTL_EXTEND); } + /// Reads this shard's record for `batch_id`. Read-only and + /// unauthenticated. Returns `Error::BatchNotFound` when the shard holds no + /// record for that id — because it was never anchored, or because + /// `prune_batches` already deleted it. pub fn get_batch(env: Env, batch_id: u64) -> Result { env.storage() .persistent() @@ -183,6 +191,10 @@ impl ReceiptShard { computed_hash } + /// Extends the TTL of the batch record at `batch_id` so an unpruned record + /// stays live. Publicly callable, no auth and no caller precondition except + /// that the shard is still active (an inactive shard panics). Returns + /// `Error::BatchNotFound` when the shard holds no record for that id. pub fn extend_batch_ttl(env: Env, batch_id: u64) -> Result<(), Error> { assert!(Self::is_active(env.clone()), "shard is inactive"); if !env.storage().persistent().has(&DataKey::Batch(batch_id)) { diff --git a/contracts/treasury/src/buyback.rs b/contracts/treasury/src/buyback.rs index 107a13ec..205ec6ec 100644 --- a/contracts/treasury/src/buyback.rs +++ b/contracts/treasury/src/buyback.rs @@ -63,12 +63,22 @@ pub struct BuybackConfig { #[contractevent] #[derive(Clone, Debug, Eq, PartialEq)] pub struct BuybackConfiguredEvent { + /// Token the treasury spends; written by `set_buyback_config` and published + /// as an event topic. #[topic] pub fee_token: Address, + /// Token the treasury buys back and burns; written by `set_buyback_config` + /// and published as an event topic. #[topic] pub governance_token: Address, + /// Router the swap is sent to; written by `set_buyback_config` and carried + /// in the event data. pub router: Address, + /// Destination the bought governance tokens are sent to; written by + /// `set_buyback_config`. pub burn_address: Address, + /// Smallest swap `execute_buyback` will perform, in fee-token units; + /// written by `set_buyback_config`. pub min_amount_in: i128, }