The Alberta Buck - Ethereum Implementation (DRAFT v0.94)

Fields group by mutability:

Issuance is opt-in per (client, insurer) pair: createCredit reverts unless the client has called setCreditIssuer(insurer, true). Anyone may still be an insurer – that is the open question in Unvetted Insurers – but nobody can put a credit in your hands uninvited.

• Immutable at mint: insurer (the address allowed to update this token), assetClass, createdAt.
• Insurer-mutable via updateCredit: faceValue, depreciationFloor, depType, depRate, depStartAt, premiumRate, lastUpdated. faceValue may not be reappraised below activatedValue – see Insurer Updates.
• Buck-mutable via activateFromBuck / deactivateFromBuck: activatedValue (capped at faceValue), lastActivatedAt. The client never writes these directly.

DepreciationType is one of NONE (land, gold), LINEAR (constant annual reduction), or DECLINING_BALANCE (continuous-compounded percentage). Three events – CreditCreated, CreditUpdated, CreditActivated – record every state change.

currentValue(tokenId) is a pure view that branches on depType:

• NONE: returns the activated face value, unchanged.
• LINEAR: loss accrues at depRate bp/year on the depreciable portion (faceValue - floor), clamped at depreciationFloor.
• DECLINING_BALANCE: discrete whole-year compounding – the factor (BP - depRate)/BP is applied once per complete year via a loop capped at 100 years, then a linear interpolation bridges the trailing partial year. No transcendental approximations.

In every case the activated portion depreciates proportionally: currentValue = depreciatedFace * activatedValue / faceValue.

A residential property would typically have two BUCK_CREDITs: one for the land (NONE) and one for the structure (LINEAR or DECLINING_BALANCE with a salvage floor).

There is no public BuckCredit.activate() function. Activation – expanding activatedValue and thus growing the holder's creditLimit – happens only atomically as part of Buck.mint(N, [tids]), and deactivation happens only atomically as part of Buck.burn(N, [tids]).

This is a deliberate consequence of the mutual-insurance pool model. Drawing take units of coverage on an NFT generates annual_premium = take * premiumRate / BP per year. Instead of charging that premium on a continuous schedule, the contract requires an upfront poolPrincipal = annual_premium * POOL_ROI_INV deposit (where POOL_ROI_INV = 10 encodes the insurer's assumed 10 % annual ROI on pool capital). At parity, the pool's investment yield on poolPrincipal exactly funds the annual premium on take in perpetuity – so a policy is a one-time purchase, not a recurring expense.

Therefore the surface BuckCredit exposes is restricted to (a) insurer-side creation / re-appraisal (createCredit, updateCredit), (b) standard ERC-721 ownership operations (transferFrom, balanceOf, ownerOf, …), and (c) two Buck-only entry points (activateFromBuck, deactivateFromBuck) which Buck._allocateMint / _allocateBurn call as part of their atomic sequences. Test fixtures that need to set up a holder with non-zero creditLimit without exercising the mint() purchase path use the BuckCreditHarness subclass's forceActivate – explicitly not present on production BuckCredit.

Buck.mint and Buck.burn are the only callers. Their per-NFT arithmetic, and the post-burn solvency rule that goes with it, are in mint(N) and burn(N).

A credit that is backing BUCK cannot change hands. BuckCredit._update – the ERC-721 hook every mint, transfer and burn passes through – refuses to move a token whose activatedValue is non-zero, with BuckCredit: credit in use. Minting is exempt (from = address(0)=), so createCredit still works, and a burn that takes coverage back to zero frees the credit to be sold again.

The reason is that the two halves of a credit position live in different places. Buck derives the holder's creditLimit from the activated value of the credits they own, while the BUCK drawn against that limit stays as a negative raw balance on the account that drew it. Let the token move and the two separate: the seller keeps an obligation with nothing behind it, and the buyer receives headroom against coverage that has already been spent. The same activated value would back BUCK twice.

activatedValue is the predicate rather than Buck's mintsBacked deliberately: it is local, so BuckCredit enforces the property without consulting Buck at all, and the guarantee does not depend on another contract being correct or even reachable. The two agree by construction – activation happens only inside Buck._allocateMint, and updateCredit may not reappraise below activated coverage.

totalCurrentValue(account) walks tokenOfOwnerByIndex and sums currentValue(tokenId) – the single call Buck.creditLimit makes to size the holder's headroom (then multiplied by currentBuckK and divided by 1e18). creditInfo(tokenId) returns (faceValue, activatedValue, premiumRate) one NFT at a time; batchCreditInfo(uint256[] tokenIds) returns a packed CreditSlice[] = (owner, faceValue, activatedValue, premiumRate) for the entire list in one external call, used by Buck _allocateMint / _allocateBurn to amortize per-NFT cross-contract dispatch overhead.

The dependency is one-way: Buck reads BuckCredit to size credit, and BuckCredit never calls Buck. BuckCredit.setBuck(address) is a one-shot post-deployment authorisation record – it names the single contract allowed to call activateFromBuck / deactivateFromBuck – and nothing more.

Earlier drafts had BuckCredit notify Buck on every NFT mutation, so that a per-block credit-limit cache in Buck could invalidate. Both the cache and the notification are gone; see The Credit Limit Is Read Live for why the cache could not have been made correct. Removing them left the call graph acyclic, which is worth more than the cache was: there is no reentrant path from BuckCredit back into Buck, so Buck's reentrancy guard needs no exemption for one.

The two-contract split, rather than collapsing into a single Diamond, is forced by the ERC-20 / ERC-721 standards: balanceOf(address) and transferFrom(address,address,uint256) share function selectors with incompatible semantics across the two standards, and the Transfer event has different indexed-argument counts. A Diamond can dispatch one selector per signature; whichever loses stops being standards-compliant and silently breaks wallets, indexers, marketplaces, and routers. See Future Directions for the modularization paths that are viable (intra-ERC-20 facets in Buck, independent UUPS for BuckCredit).

updateCredit(tokenId, newFaceValue, newDepreciationFloor, newDepType, newDepRate, newDepStartAt, newPremiumRate) is gated on msg.sender == credits[tokenId].insurer. assetClass and insurer never change.

An insurer may reappraise down to the coverage the holder has already bought, and no further: newFaceValue >= activatedValue, else BuckCredit: face below activated coverage. Activated coverage is a completed purchase – its pool principal was paid up front and funds its premium in perpetuity – so writing it down revokes a policy rather than revaluing an asset. An asset that has genuinely lost value is what a claim is for; ordinary decline is what the depreciation schedule is for, and that still moves the holder's credit limit continuously without touching the coverage itself. Every other lever stays: faceValue down to the activated line, the schedule, the floor, the premium rate.

The rule is also load-bearing for solvency. activatedValue lives in BuckCredit and mintsBacked lives in Buck; the burn is sized from the second and checked against the first. An earlier draft let a reappraisal clamp one without the other, and a holder whose credit was written down could then never unwind the position – burnable only down to the clamped line, with the remainder stuck and the credit permanently disqualified from backing BUCK again. Refusing the clamp keeps the two equal by construction, which is also what makes the transfer lock in Activation = Mint the right predicate.

A reappraisal, or ordinary depreciation, can still leave a holder's outstanding BUCK above their credit limit. That is a supported state, not a default: see Underwater Is a State, Not a Failure.

Three on-chain verifications, all reducible to BN254 precompile calls:

1. PS signature at registration: e(sigma'_1, X + m * Y) = e(sigma'_2, g_2), with m reconstructed linearly via the binding NIZK in step 2. ~147K gas.
2. Schnorr-family NIZK binding the rerandomized PS signature to the ElGamal ciphertext. Three response scalars, Fiat-Shamir bound to (sigma', E_new, pk_new, registrant_address). ~30K gas on top of step 1. Total registration ~235K, paid once per address.
3. Chaum-Pedersen NIZK at approve: proves the recipient's identity ciphertext re-encrypts the same M registered in E_alice. Fiat-Shamir binds msg.sender, spender, and chainid. ~29K gas per counterparty pair.
4. Chaum-Pedersen DLEQ at A-flavor spend (verifySpendCP): proves the spender holds a single sk_dep that opens both the note's E_n and the registered E_reg. ~36K gas via EIP-196.

src/IdentityRegistry.sol uses the BN254 helper for all curve math:

struct G1Point  { uint256 X; uint256 Y; }
struct G2Point  { uint256[2] X; uint256[2] Y; }

struct ElGamalCT { G1Point R; G1Point C; }      // (R, C) = (r*G, r*pk + M)
struct PSSig     { G1Point sigma_1; G1Point sigma_2; }
struct PSPubKey  { G2Point X; G2Point Y; }

struct RegistrationProof { uint256 e, s_m, s_r; G1Point A_ps, T_C, T_R; }
struct CPProof           { uint256 e, s1, s2;   G1Point T1, T2, T3;     }
struct SpendCPProof      { uint256 e, s;        G1Point T1, T2;         }

function register(address issuer, G1Point pk, ElGamalCT E,
                  PSSig sigma, RegistrationProof proof);
function bindContract(address target, G1Point pk, ElGamalCT E,
                      bool isPublicIdentity_, bool isCarrying);
function trustIssuer(address issuer, PSPubKey ipk);                 // governance
function verifyApprove(address sender, address spender,
                       ElGamalCT E_bob, CPProof pi) view returns (bool);
function verifySpendCP(address spender, address recipient,
                       ElGamalCT E_n, SpendCPProof cpProof) view returns (bool);
function markApproved(address spender);                              // Buck-only
function setBuck(address buck);                                      // governance, one-shot

A few non-obvious points:

• verifyApprove reads E_alice from registry storage so the caller cannot substitute a fake credential.
• bindContract is permissioned by deployment pattern, not governance: any caller may bind any yet-unbound deployed contract. The intended discipline is operator OPSEC – either the operator is the deployer and uses BuckAwareDeployer.deployAndBind for atomic deploy+bind, or the operator races to bind a pre-existing contract before anyone else. Once bound, immutable.
• markApproved (called by Buck inside approve) freezes the spender's isCarrying flag the first time anyone successfully approves them, so the carrying flavor a sender consents to cannot be retroactively flipped.
• Revocation does not un-register existing accounts; they were verified once and are never re-verified.

DeFi infrastructure – AMM pools, vaults, oracles, the Notes pool – can't generate Chaum-Pedersen proofs at approve time because the contract has no private key. Such contracts bind via bindContract(target, pk, E, isPublicIdentity_=true, isCarrying=true). Counterparties of a Public-Identity contract still call the identity-bound approve (the always-CP rule applies regardless of spender flavor), but the receipt-fragment check on the contract side is satisfied by the deterministic _identityHash rather than a per-counterparty CP receipt. Public-Identity contracts forfeit content privacy: their identity M is openable on subpoena via the operator's off-chain attestation. Encrypted-Identity contract binding (isPublicIdentity_=false) is supported by the surface but not yet used in production.

trustedIssuers is the only governance-controlled trust anchor. Adding an issuer admits a new origin of registrable identities; removing one stops new registrations under that issuer. Existing registrations are unaffected – they were verified at registration and never re-verified. Epoch-based credential renewal, key revocation, and issuer rotation are described in Identity: Epoch-Based Credential Renewal.

The transfer-path state for an account is one slot:

struct AccountState {
    BuckQty     balance;       // int80 underlying; signed.  Range = [-6.04e23, +6.04e23] raw
                               // = [-6.04e17, +6.04e17] BUCK at 6 decimals.  Negative ==
                               // NFT-backed used credit; positive == held BUCK.
    BuckSeconds buckSeconds;   // uint120 underlying; demurrage IOU integral on positive holdings
    uint40      timestamp;     // last crystallisation (safe past year 36800)
    uint16      flags;         // bit 0: demurrage routed to demurragePayer[a].
                               // bits 1-15 reserved.
}
mapping(address => AccountState) internal _state;

BuckQty is a user-defined value type wrapping int80; constructors toBuckQty(uint256) (bounds-checks against the positive cap) and toBuckQtySigned(int256) (bounds-checks both endpoints) live in BuckTypes.sol so a future width change propagates to Buck and BuckCredit in lockstep. BuckCredit always reads via asUint() (its face, floor, and activated values are non-negative by construction); Buck reads via asInt() in signed contexts and asUint() only after verifying non-negativity.

A bit in flags is the cheapest state this contract has: the word rides in the slot the transfer path already loads and stores, so testing one is free. That is exactly why it is spent only on hot-path dispatch. Cold-path bookkeeping – the count of accounts a demurrage payer carries – lives in its own mapping instead.

Outside the hot path: allowances, per-credit outstanding cover and the deposit held against it (mintsBacked[tokenId], mintsPrincipal[tokenId]), approve-time receipt fragments, and the delegated-demurrage maps. Nothing derived is stored. An account's credit limit, and therefore its balanceOf, is recomputed from live BuckCredit state on every read; there is no cached copy of it anywhere. mintsPrincipal is not an exception – it is a record of what was actually paid, which no amount of present-day state can reconstruct once the appraisal or the rate has moved.

BUCK implements IERC20 and IERC20Metadata directly – no OpenZeppelin ERC20 inheritance, so the slot layout is explicit and the transfer paths are linear (no _update override re-entry). Decimals are 6, matching USDC.

signedRawBalanceOf(a) returns the raw int80 directly; rawBalanceOf(a) clamps negatives to zero for legacy ERC-20-style readers; signedBalanceOf(a) subtracts demurrage from positive raw (returns raw directly for negative raw, since used credit accrues no demurrage). balanceOf(a) – the ERC-20 view – answers "what alice can spend right now":

held(a)         = max(0, signedRaw(a) - feeOwing(a))             // Non-Carrying
used(a)         = max(0, -signedRaw(a))
unusedCredit(a) = max(0, creditLimit(a) - used(a))
balanceOf(a)    = held(a) + unusedCredit(a)                      // Non-Carrying
balanceOf(a)    = max(0, signedRaw(a))                           // Carrying

Carrying accounts (AMM pools, Notes pool, Jubilee) hold no BuckCredit NFTs, so creditLimit == 0 and the signed-balance machinery degenerates to the prior unsigned model. feeOwing and balanceOfFees clamp to zero on negative raw – demurrage is a per-second property of held BUCK, not used credit.

mint(uint256 amount) and mint(uint256 amount, uint256[] calldata tokenIds) are the two overloads. The no-arg form runs an internal cheapest-first selector (insertion sort over the caller's NFT list – typically a handful) to minimise premium cost; the second form takes a caller-supplied order an off-chain optimizer pre-computes against effective rate, depreciation, or coverage midpoint.

burn(uint256 amount) mirrors the overload pair, but the default selector walks the holder's NFTs most-expensive-first – the dearest insurance is released first, returning the largest pool principal per BUCK burned and freeing expensive coverage capacity for re-use. The asymmetry is not arbitrageable: per-NFT inversion is symmetric (same denom on both sides), so a mint-burn round-trip on the same NFT restores both its mintsBacked and activatedValue exactly.

denom     = BP - r * POOL_ROI_INV          (must be > 0; max effective rate ~1000bp)
V         = ceil(amount * BP / denom)      present insured value that settles `amount`
principal = V - amount                     = V * r * POOL_ROI_INV / BP
take      = ceil(V * faceValue / depreciatedFace)     face units that carry V

capV   = mintsBacked * rho                     present value of the outstanding cover
netCap = capV - mintsPrincipal                 net spendable it can release
units  = ceil(amount * mintsBacked / netCap)   face units to deactivate
refund = mintsPrincipal * units / mintsBacked  the deposit those units carry

signedRawBalanceOf(holder) = -poolPrincipal       (used = principal paid to pool)
creditLimit(holder)        = sum take_i           (= activatedValue * BUCK_K / UNIT)
balanceOf(holder)          = creditLimit - used   = sum take_i - sum principal_i
                                                  = sum amount_i
                                                  = amount               (modulo rounding)
totalSupply                += poolPrincipal       (only the pool's positive contribution grows)

mint(50,000)  ->  V         = 62,500          present insured value, ceil(50,000 * 10000/8000)
                  principal = 12,500          = V * 2000/10000
                  take      = 65,651.260505   face units, ceil(V * 300,000/285,600)
                  balanceOf = 50,000          exactly what was asked for

approve(spender, amount, E_bob, pi_CP) is the identity-bound form, and the only one that lays down a receipt fragment. Both sender and spender must be isVerified. The CP proof is required regardless of the spender's identity flavor (Public-Identity or Encrypted): the always-CP rule produces a uniform per-pair audit record openable on subpoena, and engages the spender's BN254 identity key for forward security under future identity rotation. Full rationale in Why approve Is Always CP-Bound.

On success, _receiptFragments[sender][spender] = keccak256(E_bob), the standard ERC-20 allowance is written, and markApproved(spender) freezes the spender's isCarrying flag in the registry (so the carrying flavor consented to cannot retroactively flip). Per-pair cost is ~97K gas (29K CP verify + 46K allowance + 22K receipt SSTORE), paid once. Subsequent transfers between the same pair add only the bilateral check and the receipt event (~5K above an ERC-20-baseline transfer).

The plain 2-arg approve(address, uint256) is also supported, and sets nothing but the allowance. This is deliberate, and it costs no privacy: identity is enforced at transfer time, never at approve time. A bare allowance only authorises the spender to initiate a transferFrom; _identityCheckedTransfer then independently re-validates both from and to and the receipt-fragment rule for that pair – and that gate keys on (from, to), never on (from, spender). A plain-approved spender therefore cannot manufacture a transfer the rules would not already permit: they still cannot move BUCK between two non-public parties without a real CP receipt fragment laid down by the 4-arg form.

What it buys is that BUCK is a first-class citizen of stock router and Permit2 infrastructure, which requires a plain approve(PERMIT2, max), without weakening any counterparty-privacy invariant.

Both route through _identityCheckedTransfer, which enforces mutual decryptability: every private (non-public) party must hold a per-pair CP receipt fragment for its counterparty, established before the transfer by the 4-arg identity-bound approve. Only public-identity contracts may use the deterministic _identityHash fallback.

• Requires isVerified(from) and isVerified(to).
• For the to side (_receiptFragments[from][to]): if zero, requires =isPublicIdentity(from) — reverts with BUCK: sender must identity-approve recipient otherwise. Falls back to _identityHash(to) when from is public.
• For the from side (_receiptFragments[to][from]): if zero, requires =isPublicIdentity(to) — reverts with BUCK: recipient must identity-approve sender otherwise. Falls back to _identityHash(from) when to is public.
• Both guards pass only when both parties are public-identity contracts. EOA-to-EOA transfers require bilateral CP-approve; EOA-to-Public and Public-to-EOA require the private party to CP-approve the public one.

After identity checks, transfer dispatch is automatic on the sender's isCarrying flag: Carrying senders (AMM pools, the Notes pool, the Jubilee fund) take the _carryingTransfer path that crystallises both sides through now and apportions the sender's live buckSeconds proportionally to the value transferred; Non-Carrying senders take _nonCarryingTransfer, which crystallises the sender, checks the amount against balanceOf(from) = held + unusedCredit, and shifts raw balance. Because the sender is crystallised immediately before that check, the spendable figure it reads is always settled through the current block. BuckTransferReceipt(from, to, amount, fromHash, toHash) is emitted; _identityHash(a) = keccak256(abi.encode(pk, E_addr)) is deterministic per account.

BUCK accrues continuous demurrage to fund a perpetual Jubilee. Each account's buckSeconds field is the cumulative integral of (positive raw balance × dt) crystallised at timestamp; the live fee owed is

feeOwing(a) = (buckSeconds + max(0, balance) * (now - timestamp)) * BASE_RATE_PER_SEC / SCALE
            = 0    when signed raw <= 0   (no demurrage on used credit)

with BASE_RATE_PER_YEAR = 0.02 (2%/year) and SCALE = 1e27. Demurrage is a per-second property of held BUCK; accounts using credit (signed raw < 0) accrue zero fee until they climb back into positive territory. _crystallize uses max(0, signedRaw) as the rectangle height so a negative-going transfer doesn't poison the buckSeconds integral. This makes sense; any account extends into its credit only when a transfer has produced a positive BUCK balance somewhere else, where it accrues demurrage.

Visible balance:

• Non-Carrying (default for EOAs): balanceOf(a) = held + unusedCredit where held = max(0, signedRaw - feeOwing) and unusedCredit = max(0, creditLimit - used). The locked fee stays inside the account's own slot; spendable on the held side shrinks over idle periods; unused credit shrinks if BUCK_K falls.
• Carrying (AMM pools, Notes, Jubilee, etc.): balanceOf(a) = max(0, signedRaw). The account never loses visible balance to demurrage; instead, on every outflow the value-weighted age is folded into the recipient's buckSeconds so the locked fees ride with the BUCKs. Carrying accounts hold no BuckCredit NFTs and never go negative (the spendable check inside _carryingTransfer rejects any transfer that would drive raw < 0).

_crystallize(a) folds the positive time rectangle into buckSeconds and bumps timestamp; it never changes balance and tolerates negative signed raw (rectangle = 0). Carrying transfer crystallises both sides through now, apportions liveBs * value / raw of the sender's live integral to the recipient (where liveBs = buckSeconds + raw * (now - timestamp)), and settles each side in one SSTORE.

The Jubilee is a normal account at address(this), treated as Carrying. On every mint or burn, _accrueJubilee writes

_state[address(this)].balance += totalSupply * BASE_RATE_PER_SEC * elapsed / SCALE

directly into Jubilee's slot via a raw slot write – bypassing _setBalanceSigned – so totalSupply is not mutated. Demurrage is internal redistribution from positive-balance holders into the system-wide Jubilee, not fresh minting. The exact invariant:

sum_a max(0, signedRawBalanceOf(a)) == totalSupply + jubileeActual()

Jubilee is the system-wide fee escrow. Every BUCK has exactly one fee owner: non-Carrying accounts lock it silently inside their raw balance (balanceOf = raw - feeOwing); Carrying accounts (Notes pool, AMM pools, Jubilee itself) show balanceOf = raw, so their fee portion sits in Jubilee instead. The _accrueJubilee call credits Jubilee at the full totalSupply rate, covering Carrying holdings too. When Carrying BUCKs flow to a non-Carrying account via _carryingTransfer, the recipient absorbs liveBs * value / raw as extra buckSeconds, where liveBs is the sender's full live integral (crystallised history plus the current elapsed rectangle). Jubilee pre-accrued the full fee at the totalSupply rate; it now debits in exact proportion to the BUCKs transferred, with both sides settled through the current block. JubileeAccrued(delta, newBalance) surfaces every accrual.

The Jubilee is the sink that funds default coverage, perpetual-ground-rent disbursement, or a periodic balance reset – all governance-driven on-chain disbursement paths land on top of this single accumulating slot.

BUCK is a standards-compliant ERC-20 and works with stock routers, pools and Permit2. Three of its properties are unusual enough that an integration written against ordinary tokens should be checked against them.

Identity is enforced on transfer, and both sides must be registered. A transfer to an unregistered address reverts. Any contract intended to hold BUCK must be bound via IdentityRegistry.bindContract – typically with isPublicIdentity_ = true, isCarrying = true for a pool or vault (see IdentityRegistry). This is the one change most integrations need: deploy, then bind, before the first transfer in.

balanceOf moves on its own. For a non-Carrying account it is held + unusedCredit, and the credit half is a live function of the holder's insured assets and of BUCK_K. It falls as those assets depreciate, moves when an insurer reappraises one, and moves when the PID moves BUCK_K – all without any transfer occurring. Demurrage moves the held half downward continuously for the same reason. Consequences:

• Do not treat a stored balanceOf snapshot as still valid in a later block.
• Do not derive a share price or a collateral ratio from an account's balanceOf unless you intend it to track that account's insured assets. For custody questions use rawBalanceOf / signedRawBalanceOf, which report only BUCK actually held.
• Do not sample balanceOf from inside a callback you do not control: views are not covered by the reentrancy guard, and the ordinary read-only-reentrancy discipline applies.

Contracts bound as Carrying are exempt from all of this: balanceOf is exactly the raw balance, no credit and no demurrage deduction. Every pool in this system is Carrying, which is why nothing in-tree is affected.

Transfers may exceed balanceOf at the moment you read it, and may exceed held BUCK. A transfer at or below held + unusedCredit succeeds by driving the sender's signed raw negative and issuing fresh BUCK to the recipient. A pre-flight require(balanceOf(x) >= amt) in your own contract is therefore redundant, and against a stale read it is wrong in both directions. Let the transfer revert instead.

BUCK in circulation today has two provenances, both flowing through the same ERC-20:

1. BuckBasket-minted BUCK – minted by BuckBasket via the privileged Buck.mintFromBasket(to, amount) hook when a depositor pledges a TOKEN. Tracked in BuckBasket.totalOutstandingBuck; burned on redemption. The activation gate is not the BuckCredit credit limit – it is the depositor's willingness to put TOKEN (or BUCK) into the basket at the current pool valuation.
2. Externally-supplied BUCK – created by the standard Buck.mint(amount, tokenIds) path described in BUCK, backed by BuckCredit insured-asset NFTs and gated by BUCK_K. These BUCK reach the TOKEN/BUCK pools indirectly via arbitrage swaps and are the lever the PID actually pulls on.

The two supply paths converge in the basket's BUCK-side balance. Price-up TOKEN moves leave extra BUCK in the pool (TOKEN bought with BUCK by external traders); price-down moves draw BUCK out. Combined with reinvested treasury BUCK from prior redemptions, the basket's NAV typically exceeds totalOutstandingBuck – the spread is what compounds for depositors and underwrites the "profit" side of the redemption split.

Governance registers each basket constituent via addBasketToken(token, decimals, initialPriceInBuck, weightBp, feeTier). weightBp is the declared target weight in basis points; passing 0 defaults to an equal share (10000 / N). The call:

1. Renormalizes every existing constituent's targetWeightBp so the total across the N+1 constituents sums to 10000 bp, preserving each existing constituent's relative weight ratio.
2. Re-prices every existing constituent's basketAmount at the current pool spot price so its contribution to basketValueInBuck equals its declared weight share of 1.0 BUCK.
3. Finds or creates the BUCK/TOKEN V3 pool at the requested fee tier, initializes it at initialPriceInBuck (silently no-ops if already initialized), and bumps the observation cardinality so TWAP reads are available immediately after the first swap.
4. Computes the full-range tick bounds for the pool's fee-tier spacing and stores the constituent's buckIsToken0 ordering.
5. Calls controller.reprime() so the controller absorbs the dilution-discontinuity in basketValueInBuck without firing a one-cycle P/I spike.

A future rebalanceWeights(tokens[], weightBps[]) will let governance re-weight (or, with weightBp = 0, remove) one or more constituents in a single call – recomputing all basketAmount values from the current spot prices so each constituent's contribution again matches its declared share of 1.0 BUCK.

basketValueInBuck = sum_i ( basketAmount_i * pool_price_in_BUCK_i / 1e18 )

This is the direct-embodiment "process variable" – the value of one basket bundle measured in BUCK – and is what BuckKControllerDirect reads. TWAP-windowed reads (twapWindow seconds) fall back to spot if the pool is too cold to satisfy the request, so the PID degrades gracefully on a freshly-added constituent rather than freezing.

depositToken(token, tokenAmount, maxDeviationBp) has two paths chosen on token:

• Basket TOKEN deposit: the depositor pledges a registered constituent. BuckBasket reads the pool's spot price, mints tokenAmount * spotPrice worth of BUCK to itself via Buck.mintFromBasket, and LPs the (TOKEN, BUCK) pair as full-range liquidity in that constituent's pool. An ERC-721 receipt (BuckBasketReceipt) records the (BUCK principal, TOKEN principal, original token, deposit time).
• Already-minted BUCK deposit (token = address(buck)=): the depositor's BUCK is pulled in, swapped on the most underweight pool for that pool's TOKEN, partner BUCK is freshly minted against the received TOKEN, and the full (TOKEN, BUCK) pair is LP'd into the underweight pool. This is the cross-pool rebalance arrow on the deposit side.

maxDeviationBp optionally guards against TWAP/spot divergence (set to 0 during bootstrap or cold-pool deposits; non-zero rejects the deposit if |spot - TWAP| > maxDeviationBp / 10000).

redeem(receiptId, redeemBp, maxDeviationBp) settles a value claim valueClaim = redeemBuck * NAV / totalOutstandingBuck where NAV is the basket's total LP value across all pools. The claim is split across constituents by _allocateRedemption, then settled in seven phases:

1. Validate + size the receipt; compute redeemBuck as either the full buckPrincipal or a basis-point fraction.
2. Slippage guard on the depositor's original pool (the known gap: this guard should also fire on every pool actually withdrawn from – tracked as BUG #5).
3. Allocate redeemValue across pools. Each pool's "ideal" allocation is alloc_i = v_i - t_i * (NAV - redeemValue) where t_i is the pool's natural value share at target. Heavily overweight pools contribute more than their proportional share; heavily underweight pools clamp to zero. Two passes handle the equilibrium case (proportional) and the rare "must dip into underweight" case. A small-redemption fast path takes the entire claim from the most overweight pool when redeemValue is below SMALL_REDEEM_BP (1 %) of that pool's value, saving the multi-pool gas in the dominant case.
4. Burn LP from each allocated pool. TOKEN and BUCK are held inside BuckBasket; no transfers yet, so any aggregate BUCK shortfall (e.g. from a single pool dominating the allocation but carrying mostly TOKEN) can still reach back into the basket's TOKEN holdings.
5. Cover shortfall by greedy TOKEN→BUCK swaps on the pools with the most TOKEN balance left, using exact-input swaps padded by SHORTFALL_BUFFER_BP (2 %). Any residual gap below MAX_ORPHAN_DUST_WEI (1 µBUCK) is tolerated; larger gaps revert with "pool depth too thin".
6. Pay depositor the surviving TOKEN side per pool, emit one RedeemedFromPool event per touched pool (TOKEN-to-user, TOKEN-swapped, L burned).
7. Reinvest profit above the MIN_REINVEST_BUCK floor (0.001 BUCK): the BUCK side minus the principal burn is routed through _buckToLp into the most underweight pool's TOKEN and LP'd as a treasury position. Sub-floor profit stays in the basket's BUCK balance and is swept by the next redemption (still treasury-owned, just not yet LP'd). Then Buck.burnFromBasket burns the principal, totalOutstandingBuck decrements, and the deposit is finalized (cleared on full redemption; both BUCK and TOKEN principals scale down proportionally on partial).

The depositor/treasury split is approximately 50/50: full-range V3 LP is roughly 50/50 by value at any price, so the TOKEN side (depositor) and BUCK side (treasury) are roughly equal. The principal burn comes out of the BUCK side, slightly favouring the depositor.

After all deposits exit, totalOutstandingBuck = 0 and remaining LP value is entirely treasury-owned – compounded TOKEN appreciation, accumulated AMM fees, and external-arb BUCK that didn't get claimed. Modulo bounded MAX_ORPHAN_DUST_WEI per-redemption dust, this is the liveness backstop the audit trail rests on.

The contract carries BUG #N: tags for the redesign work still in flight:

• #5 – Slippage guard runs on the depositor's original pool, not on the pools actually withdrawn from.
• #6 – _buckToLp / _swapTokenForBuckExactIn swaps use the permissive MIN/MAX_SQRT_RATIO ± 1 price limit; should be TWAP-bounded to resist sandwich.
• #7 – _mostUnderweightPool / _mostOverweightPool read spot prices; should use TWAP.
• #8 – _reinvestBuck LPs into a single most-underweight pool; should mirror the redemption's proportional allocation.
• #9 – TOKEN deposits LP into the deposited token's own pool with no underweight-routing – asymmetric with the BUCK-deposit path.
• #10 – Buck.mintFromBasket bypasses BuckK's fundingFactor gate; document or fold basket-minted BUCK into the PID's accounting (see Dynamic Issuance below).
• #11 – _reinvestBuck emits no event; downstream observers can't distinguish treasury reinvestment from external arb trades.
• #13 – Late-basket-life redemptions can revert pool depth too thin when the basket NAV is too low to cover the remaining outstanding (genuine liquidity exhaustion, not dust); a graceful tail-redemption mode is future work.

BuckBasket mints BUCK at exactly the current pool spot price. That is value-neutral at the moment of deposit, but it is also the cause of a structural deflationary pressure on BUCK:

• Direct-mint adds new BUCK only when a depositor wants to LP a constituent. External BUCK demand (somebody wants to buy a TOKEN and the cheapest path is BUCK -> TOKEN swap on the BuckBasket pool) does not mint new BUCK – it just rearranges existing BUCK between the pool and the swap-caller.
• The only path that produces "free" BUCK against assets outside the basket is Buck.mint(amount, tokenIds) via BuckCredit NFTs, gated by maxLimit = totalCreditValue * currentBuckK / 1e18. When external arbitrageurs buy TOKEN with BUCK from the basket pools, BUCK gets scarce (price up vs. TOKEN ⇒ each TOKEN/BUCK pool quotes a higher TOKEN price in BUCK terms ⇒ basketValueInBuck rises above 1.0).

Sign convention (inherited from BUCK_K):

• basketValue > 1.0 (BUCK undervalued / inflation: TOKEN expensive in BUCK): error < 0 ⇒ buckK decreases ⇒ BuckCredit backed mints shrink ⇒ BUCK supply contracts ⇒ basket value falls back toward 1.0.
• basketValue < 1.0 (BUCK overvalued / deflation: TOKEN cheap in BUCK): error > 0 ⇒ buckK increases ⇒ BuckCredit backed mints expand ⇒ BUCK supply grows ⇒ basket value rises back toward 1.0.

So the closed-loop equilibrium picture is: BuckBasket establishes the TOKEN-side anchor and publishes the deviation signal; BuckKControllerDirect integrates that deviation into a credit-limit multiplier; Buck meters new supply against the multiplier; external arb agents close the loop by moving BUCK between the basket pools and the wider market. Direct-mint deposits are the value injector (asset coming in); BuckCredit backed mints under PID control are the supply regulator (BUCK going out).

BuckKControllerStatic holds one uint256 buckK (18 decimals, 1e18 = neutral). Functions: currentBuckK(), compute() (returns the stored value, non-view to match the IBuckK signature), setBuckK(uint256) (governance-only), transferGovernance(address). This is the simpler choice for early deployments where no BUCK price oracle exists yet, exercising the identity, demurrage, and Notes layers while BUCK_K is held constant.

BuckKControllerDirect is the embodiment used in tandem with BuckBasket. It has no external stablecoin intermediary; BUCK measures itself against a basket of TOKEN/BUCK Uniswap-V3 pools that BuckBasket owns and prices.

The sign convention is identical to the External-Basket variant below (all shipped gains are positive), but the error semantics are inverted relative to a "BUCK price in USDT" reading:

• basketValue > 1.0 (one BUCK now buys less than one basket – BUCK undervalued / inflation): error < 0 ⇒ BUCK_K decreases ⇒ credit contracts ⇒ supply shrinks ⇒ BUCK recovers value vs. the basket.
• basketValue < 1.0 (one BUCK now buys more than one basket – BUCK overvalued / deflation): error > 0 ⇒ BUCK_K increases ⇒ credit expands ⇒ supply grows ⇒ BUCK gives back value to the basket.

basket is wired one-shot from governance via setBasket(address) (immutable thereafter); deploying a new BuckBasket requires a new controller. reprime() external is callable only by the registered BuckBasket; BuckBasket.addBasketToken invokes it after every constituent addition so the dilution discontinuity in basketValueInBuck – a new constituent's basketAmount * spotPrice contribution appears in a single block – doesn't manifest as a one-cycle P/I spike. _reprime() recaptures P against the new process state and re-derives I so the next no-error cycle reproduces the current buckK.

Cold-pool / pre-basket behaviour: _readReferences returns (UNIT, UNIT) until setBasket fires, so the controller returns the priming buckK and runs no PID math. Once the basket is wired and observations exist, the loop is identical to the External-Basket variant – only the PV source differs.

BuckKController is the original Uniswap-V3-basket variant. It reads BUCK and a multi-token basket from separate Uniswap-V3 pools (typically priced in USDT/USDC) and treats their difference as the error term; it predates BuckBasket and remains in tree for deployments where the basket-of-pools approach is preferred over (or runs in parallel with) the direct embodiment. It follows the ezpwd::pid controller layout, ported to 18-decimal Solidity fixed-point.

Sign convention (all shipped gains are positive):

• BUCK below basket (inflation): error < 0 -> BUCK_K decreases. Credit contracts; holders running near their limit must burn BUCK to stay compliant; supply shrinks; BUCK price recovers toward basket from below.
• BUCK above basket (deflation): error > 0 -> BUCK_K increases. Credit expands; holders can mint additional BUCK against their NFTs and sell it into the pool at the premium; supply grows; BUCK price recovers toward basket from above.

Two canary tests in test/BuckKController.t.sol guard this direction (test_sign_convention_inflation_contracts_credit and test_sign_convention_deflation_expands_credit); any sign flip in the controller surface fails them within one PID cycle. See alberta-buck-ethereum-example.org for the bootstrap, equilibrium, and arbitrage examples that exercise the loop end-to-end.

prime cycle:  P = current_error;  lastBasketCost = current_basket;  primed = true;
              return buckK

dS = basketCost - lastBasketCost
D  = (error - P_prev - dS) * UNIT / dt

circuits/mint_batch.circom is a parameterised batch-mint circuit. Each pinned size N (specialised at N ∈ {1, 2, 4, 8, 16, 32}, with the smaller sizes useful for unit tests and small wallet flows) produces its own MintBatchN*Groth16Verifier.sol. The shipped Notes contract holds a single mintVerifier adapter; per-N dispatch lives inside the adapter (a single IMintVerifier chooses the right pinned verifier by cms.length). Public-signals arity is 5 regardless of N:

Per leaf, the circuit enforces a Poseidon-5 commitment opening cm_i === Poseidon(flavor_i, v_i, rho_i, idHash_i, predicate_i), Num2Bits(128) range bounds on v[i] and totalFace (closing field-overflow attacks), one sum check totalFace === sum v[i], and an N x TREE_DEPTH Poseidon-2 dual Merkle walk: priorWalk consumes ZERO_VALUE at the insertion slot to attest oldRoot, postWalk consumes cm[i] to advance rollingRoot to newRoot. Both walks share prover-supplied siblings. A keccak hash check binds cmBatchHash to the per-leaf commitments. ~6K R1CS per leaf (~1.7K opening + ~4.3K insertion).

Verifier bytecode sizes: 14.5 KB at N=16, 20.8 KB at N=32 – both under the EIP-170 24 KB ceiling. Per-mint gas: 461K at N=1 (constant ~216K Groth16 verifier dominates), 624K at N=16 (~39K/leaf – the shipped sweet-spot), 1.12M at N=32. Asymptotic per-leaf cost is ~31K. Promotion to N >= 64 needs one of the three escape hatches in alberta-buck-notes-rollup-mint.org (calldata-IC hash-pinned, sharded SSTORE2, plain SLOAD), with calldata-IC the natural fit for the Holochain wallet.

The trusted setup in scripts/snark/setup.sh uses a fixed dev-only entropy string. Production would run a multi-party ceremony per pinned N; the script is the scaffolding.

circuits/spend.circom proves redemption of a single B-shape note under an on-chain Merkle root. Public inputs [noteRoot, nullifier, face, recipient, chainId]; private witness (flavor, v, rho, idHash, predicate, pathElements[20], pathIndices[20]). Constraint groups: Num2Bits(128) on face and v, cm === Poseidon-5(flavor, v, rho, idHash, predicate), Tornado-style depth-20 Merkle inclusion under noteRoot, B-tag nullifier Poseidon-3(rho, idHash, 4242), and value conservation face * 1 === v * 1 with a quadratic anchor. ~12,000 R1CS. SpendGroth16Verifier takes the 5-element public-signals tuple; SpendVerifierAdapter presents the narrow ISpendVerifier.

circuits/spend_a.circom V2 is the A-flavor (identity-bound) sibling. Public inputs grow to [noteRoot, nullifier, face, recipient, chainId, E_n.R.x, E_n.R.y, E_n.C.x, E_n.C.y] (9 total). Adds the A-tag nullifier Poseidon-3(rho, idHash, 4243), a flavor-in-{1,2} gate, and an in-circuit Poseidon-8 binding gate Poseidon-8(E_n, issuerData) === idHash (~265 R1CS) that pins the publicly-revealed E_n to the leaf at mint time. Total ~13,300 R1CS.

The cryptographic identity gate – proving the spender holds a single sk_dep that opens both E_n and the registered E_reg – lives in IdentityRegistry.verifySpendCP rather than the circuit. In-circuit BN254 G1 arithmetic over the BN254 scalar field would have cost +250K R1CS per group operation; off-chain CP-DLEQ verified via EIP-196 precompiles costs ~36K gas instead. Notes.spendACP calls the Groth16 verifier and verifySpendCP atomically; both must succeed. The DLEQ is a 4-element Sigma proof:

Prover picks t in Fr, computes T1 = t*G, T2 = t*(R_reg - R_n). Challenge: e = H(R_n, R_reg, C_n, C_reg, pk_dep, T1, T2, recipient, chainid). Response: s = t + e*sk_dep. Proof: (e, s, T1, T2) – 4 field elements, ~36K gas to verify on-chain.

The invariant the two layers together enforce: A-note loss-recovery via identity re-issuance is impossible by design. sk_rec must be backed up like a hardware-wallet seed; loss is terminal. Companion documents Notes and Notes Flow document the wallet-side implications.

Notes is decoupled from the SNARK toolchain via narrow interfaces:

interface IMintVerifier {
    function verifyMint(bytes proof, uint256 oldRoot, uint256 newRoot,
                        uint256 nextLeafIndex, uint256 totalFace,
                        uint256[] calldata cms) external view returns (bool);
}
interface ISpendVerifier {
    function verifySpend(bytes proof, uint256 root, uint256 nullifier,
                         uint256 face, address recipient, uint256 chainId)
        external view returns (bool);
}
interface ISpendAVerifier {
    function verifySpendA(bytes proof, uint256 root, uint256 nullifier,
                          uint256 face, address recipient, uint256 chainId,
                          uint256 enRx, uint256 enRy, uint256 enCx, uint256 enCy)
        external view returns (bool);
}

Stub implementations (StubMintVerifier / StubSpendVerifier) ship for unit tests that exercise state transitions unrelated to the SNARK. The production Adapter contracts decode the proof as (uint256[2], uint256[2][2], uint256[2]), build the public-signals tuple, and forward to the snarkjs-generated Groth16 verifier. mintVerifier is a singleton IMintVerifier adapter that internally dispatches by cms.length to the correct pinned MintBatchN*Groth16Verifier; spend verifiers are likewise singletons. Swapping any of them is a single governance call.

src/Notes.sol is constructed with (buck, mintVerifier, spendVerifier, governance). The A-flavor spend verifier and the identity registry are wired post-construction via governance setters (setSpendAVerifier, setIdentityRegistry); until both are set, spendACP reverts with Notes: A-spend disabled or Notes: identity registry not set. Its state is intentionally lean – per-leaf insertion math now lives in the SNARK:

• Verifier handles: singleton mintVerifier (the adapter that dispatches by batch size), singletons spendVerifier for B-spend and spendAVerifier for A-spend, plus the identityRegistry used by spendACP for verifySpendCP. All swappable by governance.
• Audit / double-spend state: mapping(uint256 => bool) nullifiers, uint256 noteFaceSum.
• Tree state: uint32 nextLeafIndex and uint256[ROOT_HISTORY_SIZE=30] roots with uint8 currentRootIndex. filledSubtrees, zeros[], and per-cm uniqueness checks are gone – duplicate openings are economically self-punishing via the deterministic nullifier (one spend nullifies every copy of the same opening; the duplicator forfeits their mint).

mint(proof, oldRoot, newRoot, nextLeafIndex, totalFace, cms) asserts cms.length > 0, checks oldRoot == roots[currentRootIndex] and nextLeafIndex == self.nextLeafIndex (stale-state guards), field-bounds each cms[i] against FIELD_R, dispatches to mintVerifier (which forwards to the per-N pinned Groth16 verifier internally), pulls totalFace BUCK via transferFrom(caller, this, totalFace), writes newRoot into the ring buffer at (currentRootIndex + 1) % ROOT_HISTORY_SIZE, advances nextLeafIndex by cms.length, bumps noteFaceSum by totalFace, and emits Minted(issuer, totalFace, startIndex, count, newRoot). Per-leaf Appended events are gone; the commitments live in calldata for off-chain replayers.

spend(proof, root, nullifier, face, recipient) (B-flavor) requires recipient != 0, face > 0, isAcceptedRoot(root) (root in the recent-roots window), and !nullifiers[nullifier]. Forwards to spendVerifier, marks the nullifier burned, decrements noteFaceSum, and calls buck.transfer(recipient, face). Because the Notes pool is bound under the Carrying flag, buck.transfer dispatches to the carrying path automatically – the recipient absorbs the pool's average demurrage age via buckSeconds, preserving the SNARK's face === v invariant at the ERC-20 boundary. Spent(nullifier, face, recipient) closes the spend.

spendACP(proof, root, nullifier, face, recipient, E_n, cpProof) (A-flavor) is identical except it also calls identityRegistry.verifySpendCP(msg.sender, recipient, E_n, cpProof) atomically; both verifications must succeed.

Alice obtains a PS-signed credential off-chain from a trusted issuer (the Alberta government, ATB Financial, etc.), rerandomizes it, generates a fresh ElGamal key pair, encrypts her identity point M = m·G under her public key, and produces the Schnorr-family NIZK binding the rerandomized sigma to the ciphertext. IdentityRegistry.register(issuer, pk, E, sigma', proof) verifies both via BN254 precompiles in about 235K gas. After this call isVerified[alice] = true and Alice can touch BUCK. She repeats steps 2-3 for every Ethereum account she controls; the issuer never sees those accounts.

Alice calls BUCK.mint(50_000e6) – the no-arg form, so the built-in selector sorts her credits by premiumRate ascending: LandCo (50bp) first, then HomeCo (200bp). At BUCK_K = 1e18, and writing BUCK amounts rather than raw 6-decimal units:

1. buckK.compute() runs the PID cadence. The static controller returns fundingFactor() = 0=, so the counter-cyclical reserve gate is disabled and no pre-mint balance is captured.
2. The allocator walks #42 first: denom = 10000 - 50*10 = 9500, avail = 200,000 - 0, netCap = avail * 9500 / 10000 = 190,000. Since netCap >= 50,000 the closed-form partial fill lands it in one credit: take = ceil(50,000 * 10000 / 9500) = 52,631.578948, principal = take - 50,000 = 2,631.578948. #43 is never touched.
3. activateFromBuck(#42, alice, take) grows activatedValue to take, and mintsBacked[#42] with it. From this moment #42 cannot be transferred.
4. insurancePool is credited the principal and Alice's signed raw is debited the same: the principal's 10 % assumed ROI (263.16/yr) exactly funds the 50bp annual premium on 52,631.58 of coverage (263.16/yr), in perpetuity.

End state, all of it live-derived rather than stored:

activatedValue[#42] = mintsBacked[#42] = 52,631.578948
creditLimit(alice)                     = 52,631.578948   (#42 is NONE-schedule, so no haircut)
signedRawBalanceOf(alice)              =    -2,631.578948
balanceOf(alice)                       =    50,000.000000   (limit - used)
totalSupply                           +=     2,631.578948   (the pool's positive contribution)

Alice now holds no BUCK at all and can spend 50,000 of it. Had the selector reached #43 instead, she would have got the same 50,000 – the gross-up in mint(N) and burn(N) would simply have activated more of #43's face to carry it, and charged premium on the 285,600 appraisal rather than the 300,000 the structure was worth when it was new.

Alice's wallet reads Bob's pk_bob from IdentityRegistry, decrypts E_alice (it knows sk_alice) to recover M, and re-encrypts under pk_bob with fresh randomness as E_bob = (r_b·G, r_b·pk_bob + M). It produces a Chaum-Pedersen NIZK pi_CP = (e, s_1, s_2) proving E_bob encrypts the same M registered in E_alice, with Fiat-Shamir bound to msg.sender = alice, spender = bob, chainid.

BUCK.approve(bob, 10_000e6, E_bob, pi_CP) verifies both parties are isVerified, runs IdentityRegistry.verifyApprove (29K gas), stores ~_receiptFragments[alice][bob] = keccak256(E_bob), calls markApproved(bob) to freeze his isCarrying flag, and writes the ERC-20 allowance.

Off-chain (e.g. via Holochain), Alice delivers the matching identity_data and E_bob ciphertext to Bob's wallet. Bob decrypts to recover M' and asserts H(identity_data) * G === M' – the two-channel binding from the Identity document.

BUCK.transferFrom(alice, bob, 10_000e6) debits the allowance, runs _identityCheckedTransfer (both parties verified, _receiptFragments[alice][bob] ! 0=), and dispatches to the Non-Carrying path (Alice is not Carrying). Tokens move; BuckTransferReceipt(alice, bob, 10_000e6, fromHash, toHash) is emitted. An auditor with subpoena power over either Alice or Bob can recover the underlying identities; an outside observer learns only that addresses Alice and Bob exchanged 10,000e6.

Alice picks flavour A2 and values [100e6, 25e6] (totalFace 125e6). Her wallet pads the live pair with 14 dummies (v=0) so the batch lands on the smallest pinned circuit (N=16), snapshots (oldRoot, nextLeafIndex) from chain, derives the depth-20 sibling paths in submission order, and runs snarkjs groth16 fullProve against build/snark/mint_batch_n16/mint.wasm and mint_final.zkey. The proof triple is abi-encoded into proofBytes.

On-chain:

1. BUCK.approve(notes, 125e6, E_notes, pi_CP_notes) – the always-CP rule applies even though Notes is bound under a Public Identity. The receipt fragment is openable on subpoena.
2. Notes.mint(proofBytes, oldRoot, newRoot, nextLeafIndex, 125e6, [cm[0]..cm[15]]) – the adapter dispatches internally by cms.length=16 to its pinned MintBatch16 Groth16 verifier. On success, 125e6 BUCK moves from Alice to Notes, roots[] advances to the SNARK-attested newRoot, nextLeafIndex advances by 16, noteFaceSum + 125e6=. Alice keeps the live openings privately; the dummies are discarded.

Later, the holder of one of Alice's notes (Alice herself, or a bearer she off-chain handed the opening to) redeems cm[0] for 100 BUCK to recipient:

1. The wallet reconstructs (pathElements[20], pathIndices[20]) for cm[0] by replaying the Minted event log and pulling cms[] from each batch's calldata.
2. snarkjs groth16 fullProve against spend.wasm / spend_final.zkey produces a proof binding [currentRoot, Poseidon-3(rho, idHash, 4242), 100e6, recipient, 1] to the witness.
3. Notes.spend(proofBytes, currentRoot, nullifier, 100e6, recipient) – the contract checks the root window, rejects a previously-seen nullifier, runs the adapter (~360K gas total), marks the nullifier burned, decrements noteFaceSum, and calls buck.transfer(recipient, 100e6). Notes is bound Carrying, so the transfer dispatches to the carrying path automatically: the recipient receives the full 100e6 and absorbs an amount-weighted share of the pool's average demurrage age via buckSeconds.

If HomeCo later reappraises the structure at $280K, that is allowed – #43 carries no activated coverage, so the floor in Insurer Updates does not bind, and Alice's future capacity against it drops accordingly. What HomeCo cannot do is write #42's coverage down: LandCo is #42's insurer, and even LandCo may not reappraise below the 52,631.58 Alice has bought.

Meanwhile #42 keeps depreciating on its schedule – NONE, so not at all here, but a depreciating credit would pull creditLimit down under Alice continuously. If it fell below her drawn 2,631.58 she would be underwater: she could not burn until she reacquired BUCK and repaid, her insurance would stay in force regardless, and the Jubilee relief accruing against #42's coverage-age would shrink the cost of closing the position year on year.

BUCK/USDT and basket pool prices use Uniswap V3 TWAPs (600 s shipped, governance-tunable per pool), so manipulation requires sustained capital commitment over the full window proportional to pool depth. The BuckKControllerV3TwapTest suite verifies that a single-block flash-shape attack driving BUCK to $0.50 leaves spot collapsed but TWAP unchanged at ~$1.000002, with the PID computing off the unchanged TWAP. When/if Chainlink basket feeds are adopted later, the Chainlink branch of _getBasketCost must verify updatedAt is within an acceptable window (~1 hour) and revert if stale.

This is the one thing on this page that must close before mainnet, and it is not closed.

createCredit is permissionless. Any address may issue a BUCK_CREDIT naming itself the insurer; there is no vetting of any kind. updateCredit is gated on msg.sender == insurer, but becoming an insurer in the first place is not gated at all.

The consequence is unbacked issuance, not merely a nuisance. A credit's faceValue and premiumRate are whatever its issuer says they are, and a zero-premium credit costs nothing to draw on – poolPrincipal == 0, so the counter-cyclical funding gate is inapplicable by design. So a single verified account can write itself a policy on an asset it never names, and mint against it:

mallory issues herself a zero-premium credit, faceValue 1,000,000,000
mint(500,000,000)   ->  principal paid   0
                        spendable        500,000,000 BUCK
                        transferred on   totalSupply 0 -> 500,000,000

Nothing downstream catches it. totalCurrentValue sums whatever credits an account holds without asking who issued them, and the identity layer only establishes that the minter is a registered person – not that the insurer is good for anything.

The recipient opt-in below does not close this, and cannot: the attacker is both insurer and client, so she accepts herself. Only vetting the insurer closes it. The intended shape is deliberately not a governance allowlist – issuance stays open to anyone who can demonstrate they are good for the claims: on-chain solvency (a buffer held, and provably available to the parametric payout trigger) plus a rating. That system is unbuilt. Until it exists, BUCK's supply is bounded only by the honesty of everyone holding a registered identity.

A credit only lands where its recipient asked for it. A client calls setCreditIssuer(insurer, true) before that insurer may issue to them; the flag is per-pair, revocable, and governs only new issuance, since credits already held may be backing BUCK. The rule is uniform – naming yourself the insurer does not exempt you – which keeps the invariant statable in one line and declines to open a carve-out shaped exactly like the attack above.

What this closes is the gas-griefing vector. A credit costs its holder gas forever after: totalCurrentValue walks tokenOfOwnerByIndex over every token the account owns, and since the credit limit is read live, that walk runs on every outbound transfer from a non-Carrying account. Without the opt-in an attacker could raise a chosen address's transfer cost without bound for the price of the mints, and the victim could not refuse delivery – ERC-721 _mint needs no consent from the receiver. A holder can still dispose of an unwanted credit by transferring it away, since an unactivated credit is freely transferable, but that is a remedy they should never have had to reach for.

It is not a substitute for vetting. It bounds who may put a credit in your hands; it says nothing about whether that credit is worth anything.

An insurer may reappraise faceValue downward, but not below coverage the holder has already bought (see Insurer Updates). So an insurer cannot cancel a policy, cannot strand a position, and cannot by itself put a holder into default: the worst it can do is reduce future borrowing capacity against that asset, and – via the depreciation schedule – let the holder's credit limit decline over time. A holder pushed below their limit that way is in the supported underwater state, not a defaulted one.

That leaves the residual risks from an insurer who has been vetted: refusing to honour a claim, and setting a punitive premiumRate on new coverage. Multi-insurer market discipline is the natural check, and a rating that responds to claim behaviour is the intended mechanism. Time-locks on insurer updates (e.g. 7-day delay for reductions > 20 %) remain a future enhancement. For the prior question – how an insurer becomes vetted at all – see Unvetted Insurers.

Every state-mutating entry point on Buck carries a transient-storage mutex; the design and the measured cost are in Reentrancy Guard. The guard has no exemptions.

The guard is defence in depth rather than a fix for a live hole. Every outbound call Buck makes today is either a STATICCALL – including the PID controller's oracle reads, which sit behind an internal view _readReferences() – or a call into one of the three immutable, address-locked system contracts, none of which reach arbitrary code. What the guard protects against is the future: BuckCredit behind a UUPS proxy (see Future Directions), or any ERC-721 receiver hook added to the activation path. The window it closes is real and specific: _allocateMint activates coverage – which grows credit headroom immediately – before debiting the minter the pool principal, so mid-mint balanceOf overstates, and _subBalance does not re-check the limit on the way out.

Note that view functions are not guarded and cannot be: read-only reentrancy against balanceOf is a hazard for integrations, which must not sample a BUCK balance from inside a callback they do not control. See Integrating with BUCK.

insurancePool holds the cumulative pool principal for every outstanding mint. Burn requires the pool's spendable balance to cover the proportional refund; if the pool is drained out-of-band the burn reverts. Today no path drains the pool: it is not a verified identity (so no identity-checked transfer can move BUCK out of it) and holds no NFTs (so it cannot self-burn via the allocator). Adding governance-controlled disbursement requires explicit accounting of how the pool's invariant (poolBalance >= sum of all outstanding mint principals) is preserved.