From 7e86a0d18ffb48aba68fd495ea1fed82153172df Mon Sep 17 00:00:00 2001 From: NingLin Liu Date: Wed, 28 Oct 2026 12:41:43 +0800 Subject: [PATCH] docs(confidential): align compliance and protocol docs with the code The confidential token docs had drifted from the code in a few places (found in #949): - compliance.md: with compliance None, only freeze/unfreeze revert with NotConfigured; clawback and force_revoke_spender revert with AccountNotFrozen, and set_compliance_config has no guard. - compliance.md: the default on_deposit does not require the depositor to be registered; the core only checks `to`. - compliance.md: the on_register sample takes `&RegisterPayload`, not `Val`. - proof-system.md: protocol 28 is the effective minimum for deployment (soroban-sdk 28 and ultrahonk_soroban_verifier 0.1.0). - circuits/vks/README.md: note that nargo 1.0.0-beta.11 is used and tested even though the verifier crate lists beta.9. Fixes #949 --- packages/confidential/circuits/vks/README.md | 5 +++++ packages/confidential/docs/compliance.md | 8 ++++---- packages/confidential/docs/protocol/proof-system.md | 2 +- 3 files changed, 10 insertions(+), 5 deletions(-) diff --git a/packages/confidential/circuits/vks/README.md b/packages/confidential/circuits/vks/README.md index 1a4967c6a..410e726bb 100644 --- a/packages/confidential/circuits/vks/README.md +++ b/packages/confidential/circuits/vks/README.md @@ -31,6 +31,11 @@ Reproducible from the circuit sources with the pinned toolchain: Both versions are pinned in `.github/workflows/noir.yml`. CI re-runs the extraction and diffs against the files here; any drift fails the build. +The `ultrahonk_soroban_verifier` crate's README lists Nargo `1.0.0-beta.9` + +Barretenberg `0.87.0` as its compatible tooling. This repository uses and +tests `1.0.0-beta.11` with the same `bb 0.87.0`, and the proofs it +produces verify in the test suite. + ## Proving Proofs the deployed verifier accepts must be generated with the same diff --git a/packages/confidential/docs/compliance.md b/packages/confidential/docs/compliance.md index 744bb8cc1..bea51f420 100644 --- a/packages/confidential/docs/compliance.md +++ b/packages/confidential/docs/compliance.md @@ -22,7 +22,7 @@ struct ComplianceConfig { | `policy` | Optional external authorization contract ([Policy Contract](#policy-contract)). `None` means no policy gate. | | `sac_passthrough` | When `true`, every state-modifying operation additionally consults the underlying SAC's `authorized()` check ([Contract-Level Freeze](#contract-level-freeze)). | -The constructor takes `compliance: Option`. When `None`, the contract behaves exactly as [the protocol specification](protocol/README.md) specifies: no pre-checks run, and the admin-gated entry points in [Interface Summary](#interface-summary) revert with `NotConfigured`. +The constructor takes `compliance: Option`. When `None`, the contract behaves exactly as [the protocol specification](protocol/README.md) specifies: no pre-checks run. Of the admin-gated entry points in [Interface Summary](#interface-summary), `freeze` and `unfreeze` revert with `NotConfigured`. Because no account can be frozen, `clawback` and `force_revoke_spender` revert with `AccountNotFrozen`. `set_compliance_config` has no such guard: it is the single setter for both the deployment-time write and later rotations, so it can also turn compliance on after construction. ### Admin Authority @@ -98,7 +98,7 @@ The policy address is rotatable via `set_compliance_config` ([Interface Summary] The compliance surface of [Contract-Level Freeze](#contract-level-freeze) and [Policy Contract](#policy-contract) is delivered as `ComplianceHooks`, a turnkey implementation of the contract's `Hooks` trait. Deployments that need behaviour beyond the default gating — for example, the deposit-side policies sketched below — replace `ComplianceHooks` with a bespoke `Hooks` impl. The custom impl typically delegates to the same primitives the default uses (`storage::gate_account`, `storage::check_policy`, `storage::check_sac`) and only overrides the callbacks that require non-default semantics. -`deposit` is the canonical entry point for customization because it is the only operation where `from` may legitimately be an address that has never registered with the contract (the depositor only needs to hold the underlying SEP-41). The default `ComplianceHooks::on_deposit` gates both `from` and `to` unconditionally, which means every depositor must first register and pass the policy gate. Deployments that need other semantics override `on_deposit`. +`deposit` is the canonical entry point for customization because it is the only operation where `from` may legitimately be an address that has never registered with the contract (the depositor only needs to hold the underlying SEP-41). The default `ComplianceHooks::on_deposit` gates both `from` and `to` (freeze, policy and SAC checks) but does not require `from` to be registered: the core checks registration for `to` only. An unregistered depositor is therefore accepted as long as it is not frozen and the policy and SAC authorize it. Deployments that need other semantics override `on_deposit`. ### Permit Unregistered Deposits @@ -151,7 +151,7 @@ At `register`, the account owner chooses which `auditor_id` the account binds to ```rust impl Hooks for ApprovedAuditorHooks { - fn on_register(e: &Env, account: &Address, auditor_id: u32, payload: Val) { + fn on_register(e: &Env, account: &Address, auditor_id: u32, payload: &RegisterPayload) { let approved: Vec = e .storage() .instance() @@ -278,7 +278,7 @@ impl Token { fn unfreeze(e: Env, account: Address, operator: Address); fn is_frozen(e: Env, account: Address) -> bool; - // Config rotation (admin auth per Admin Authority, reverts when compliance.is_none()) + // Config write and rotation (admin auth per Admin Authority; also works when compliance.is_none()) // Replaces the entire ComplianceConfig in one call. fn set_compliance_config(e: Env, config: ComplianceConfig, operator: Address); diff --git a/packages/confidential/docs/protocol/proof-system.md b/packages/confidential/docs/protocol/proof-system.md index e9d9f50b1..ebf66cf15 100644 --- a/packages/confidential/docs/protocol/proof-system.md +++ b/packages/confidential/docs/protocol/proof-system.md @@ -140,7 +140,7 @@ where $$[x]\_1 = x \cdot G\_1$$ and $$[x]\_2 = x \cdot G\_2$$ are BN254 group el ## Dependency: CAP-80 -[CAP-80](https://github.com/stellar/stellar-protocol/blob/master/core/cap-0080.md) introduces the host functions required for efficient UltraHonk verification and on-chain Grumpkin point arithmetic. The rollout spans two protocols; both are required, so **protocol 26 is the effective minimum**. +[CAP-80](https://github.com/stellar/stellar-protocol/blob/master/core/cap-0080.md) introduces the host functions required for efficient UltraHonk verification and on-chain Grumpkin point arithmetic. The rollout spans two protocols, 25 and 26, and both are required by the host functions. The contracts are built with `soroban-sdk` 28 and the `ultrahonk_soroban_verifier` 0.1.0 crate, which require Stellar protocol 28 or newer, so **protocol 28 is the effective minimum for deployment**. - **Protocol 25:** `bn254_g1_{add, mul}`, `bn254_multi_pairing_check`. - **Protocol 26:** `bn254_g1_msm`, `bn254_g1_is_on_curve`, `bn254_fr_{add, sub, mul, inv, pow}` -- the $$\mathbb{F}\_r$$ scalar arithmetic underpinning Grumpkin point operations.