fix: reconcile the two identity registries, and cap the faucet globally

Three defects found on a pass over the parts where one component mirrors another.

**subTier disagreed across the two IIdentityRegistry implementations.**
`CleanverseIdentityRegistry._toUint8` folds anything above 99 to 0 and blocks
pricing; the devnet mirror returned it verbatim and the relayer clamped to 255.
So an out-of-spec subTier of 150 was refused on Monad and priced at the top band
in tests — a devnet suite able to prove something production does not do. Both
now fold, pinned by testFuzz_outOfRangeSubTierReadsAsZero. 75 tests.

**Jurisdiction had three representations of one country.** The contract derives
uint16(bytes2(group)) — 21843 for "US" — while the relayer's lookup table
answered 1. The table is gone; the mirror now derives what the contract derives,
so any two-letter group works and there is no map left to drift. Dormant today,
since Cleanverse leaves the group empty and Covenant reads 0 as unconstrained.

**The faucet had no global limit.** Its per-address cooldown was not a cap:
cycling fresh addresses walks past it, and each pass mints 250,000 cvaUSD. No
contract is at risk — every cash leg pulls only from msg.sender — but the
settlement token could be inflated without bound. A rolling-hour cap now sits
alongside the cooldown, counted only after a mint actually lands so a Cleanverse
timeout does not consume the budget.

Also corrects STATIC-ANALYSIS.md. It claimed the reentrancy ordering was safe
only because cvaUSD has no transfer callback. It is safe regardless: a reentrant
settle burns the note, so fund's trailing _transfer then reverts on a token that
no longer exists and unwinds everything, and the mirror case in settle behaves
the same way including when obligor == supplier. The trailing writes are the
guard, not a residual risk.

Author: 0xFearless-1

README.md

@@ -1,7 +1,7 @@
 # Covenant
 
 [![CI](https://github.com/UnityNodes/Covenant/actions/workflows/ci.yml/badge.svg)](https://github.com/UnityNodes/Covenant/actions/workflows/ci.yml)
-[![Tests](https://img.shields.io/badge/tests-74%20passing-2ea44f)](https://github.com/UnityNodes/Covenant/actions/workflows/ci.yml)
+[![Tests](https://img.shields.io/badge/tests-75%20passing-2ea44f)](https://github.com/UnityNodes/Covenant/actions/workflows/ci.yml)
 [![Coverage](https://img.shields.io/badge/coverage-97.5%25%20lines%20%C2%B7%2094.1%25%20branches-2ea44f)](docs/SCALE.md)
 [![Sourcify](https://img.shields.io/badge/Sourcify-5%2F5%20exact__match-6E54FF)](https://repo.sourcify.dev/10143/0xAa15aBFC21424B842B5272BdeD23158D180E785A)
 
@@ -158,10 +158,10 @@ Full adversarial review, including six owner-only findings that were deliberatel
 forge build && forge test -vv
 ```
 
-74 tests across three kinds:
+75 tests across three kinds:
 
 - **49 example tests** — happy-path lifecycle, subTier repricing, `AlreadyConfirmed` / `AlreadyOriginated` replay guards, escrow and token-level compliance gates, EIP-712 signed confirmation (valid / expired / wrong-signer), and the live identity adapter against a mock CVI that reproduces the real contract's revert-on-missing-pass behaviour.
-- **16 property tests** ([`test/Fuzz.t.sol`](test/Fuzz.t.sol)) — 256 randomised runs each. The rate curve is monotonic across all 256 subTiers and never prices above face; two different obligations never share a key; a whole lifecycle conserves value for any face value and any maturity; no unverified address anywhere in the address space can hold a note.
+- **17 property tests** ([`test/Fuzz.t.sol`](test/Fuzz.t.sol)) — 256 randomised runs each. The rate curve is monotonic across all 256 subTiers and never prices above face; two different obligations never share a key; a whole lifecycle conserves value for any face value and any maturity; no unverified address anywhere in the address space can hold a note.
 - **9 system invariants** ([`test/Invariant.t.sol`](test/Invariant.t.sol)) — 12,800 randomly ordered calls each, from nine wallets spread across every band, with identity revocation and time skips mixed in. The escrow's balance is zero at every step, value is conserved, and no note is ever priced off the published curve.
 
 **Coverage: 97.5% of lines and 94.1% of branches across the five deployed contracts** (`forge coverage`). `ObligationRegistry` — the core mechanic — is at 100% on every metric.

dashboard/src/app/api/onboard/route.ts

@@ -28,6 +28,21 @@ const MINT_AMOUNT = 250_000_000_000n; // 250,000.000000 cvaUSD
 const COOLDOWN_MS = 60 * 60 * 1000;
 const lastOnboard = new Map<string, number>();
 
+// The per-address cooldown alone is not a limit: cycling fresh addresses walks straight
+// past it, and every pass through mints 250,000 real cvaUSD. No contract is at risk —
+// every cash leg pulls only from msg.sender — but the settlement token can be inflated
+// without bound, which is worth stopping even on a testnet. So the window is global as
+// well as per-address.
+const GLOBAL_WINDOW_MS = 60 * 60 * 1000;
+const GLOBAL_MAX_PER_WINDOW = 25;
+const recentOnboards: number[] = [];
+
+function globalBudgetLeft(): boolean {
+  const cutoff = Date.now() - GLOBAL_WINDOW_MS;
+  while (recentOnboards.length > 0 && recentOnboards[0] < cutoff) recentOnboards.shift();
+  return recentOnboards.length < GLOBAL_MAX_PER_WINDOW;
+}
+
 const monadTestnet = defineChain({
   id: CHAIN_ID,
   name: "Monad Testnet",
@@ -59,6 +74,13 @@ export async function POST(request: Request) {
     return bad(`This wallet was onboarded recently. Try again in ${minutes} minute${minutes === 1 ? "" : "s"}.`, 429);
   }
 
+  if (!globalBudgetLeft()) {
+    return bad(
+      `The desk has onboarded ${GLOBAL_MAX_PER_WINDOW} wallets in the past hour, which is its cap. Try again shortly, or switch to Demo mode — it needs no wallet at all.`,
+      429,
+    );
+  }
+
   const addresses = CHAIN_ADDRESSES[CHAIN_ID];
   const publicClient = createPublicClient({ chain: monadTestnet, transport: http() });
 
@@ -99,7 +121,10 @@ export async function POST(request: Request) {
     const receipt = await publicClient.waitForTransactionReceipt({ hash: mintTx });
     if (receipt.status !== "success") return bad("The mint transaction was mined but failed. Try again.", 502);
 
+    // Counted only once the mint has actually landed, so a Cleanverse timeout or a
+    // failed mint does not silently consume the hour's budget.
     lastOnboard.set(address.toLowerCase(), Date.now());
+    recentOnboards.push(Date.now());
 
     const apass = await queryApass(address);
     return Response.json({

dashboard/src/app/pitch/page.tsx

@@ -33,7 +33,7 @@ const CLEANVERSE_ADDRESSES = [
 const COMPETITORS = ["Centrifuge", "Huma Finance", "Polytrade", "Goldfinch", "Credix", "Defactor"];
 
 const STATS = [
-  { figure: "74/74", label: "Foundry tests · fuzz + invariants · 97.5% lines, 94.1% branches" },
+  { figure: "75/75", label: "Foundry tests · fuzz + invariants · 97.5% lines, 94.1% branches" },
   { figure: "0", label: "oracles between Cleanverse and the gate" },
   { figure: "3", label: "independent compliance re-checks per cash leg" },
 ];

docs/Covenant-pitch-deck.pdf

@@ -66,18 +66,25 @@ The business state is written *before* the external call — `n.funded`,
 `fund` hits `AlreadyFunded` and a reentrant `settle` hits `AlreadySettled`. What lands
 after the call is ERC-721 ownership (`_owners`), which is why the detector fires.
 
-The honest statement of the residual risk, which is worth more than "safe":
-
-> During `fund`'s external call, the note is still owned by the supplier. If the
-> settlement asset could hand control back to a party able to call `settle`, that call
-> would pay face value to the supplier instead of the financier. It cannot, because
-> `settle` requires `msg.sender == n.obligor` and cvaUSD is a plain ERC-20 with no
-> transfer callback — verified on-chain, not assumed. **The safety of this ordering
-> depends on that property of the asset.** An ERC-777-style settlement asset would
-> require moving `_transfer` above the escrow call.
-
-Named here so that swapping the settlement asset is known to be a change that has to
-come back to this paragraph.
+This section used to end with a caveat: that the ordering was safe only because cvaUSD is
+a plain ERC-20 with no transfer callback, and that an ERC-777-style asset would require
+moving `_transfer` above the escrow call.
+
+**That was too cautious.** Working the reentrant cases through shows the trailing writes
+are not a weakness left over after the external call — they are the guard.
+
+> Suppose the settlement asset *can* hand control back mid-transfer, and the obligor
+> re-enters `settle` during `fund`. `settle` proceeds — `funded` is already true — pays
+> face value to the current holder, and burns the note. Control returns to `fund`, which
+> then runs `_transfer(supplier, financier, tokenId)` on a token that no longer exists.
+> ERC-721 reverts, and the whole transaction unwinds, settlement included. The same holds
+> for a reentrant transfer: `_transfer` reverts because the supplier is no longer the
+> owner. Every reentrant path that touches note state makes the outer call fail closed,
+> including the multi-role case where `obligor == supplier`.
+
+So the safety does not rest on a property of the asset. It rests on `fund` and `settle`
+each ending with a write that cannot succeed if their own state was disturbed. The
+detector is right that the pattern deserves a look; the look concludes it holds.
 
 ## Medium — `uninitialized-local` in `CleanverseIdentityRegistry._read`
 

docs/STATIC-ANALYSIS.md

@@ -9,30 +9,35 @@ export interface OnchainIdentity {
 }
 
 const ACTIVE_STATUS = 1;
-const MAX_UINT8 = 255;
-
-const JURISDICTION_CODES: Record<string, number> = {
-  US: 1,
-};
 
+/// Cleanverse documents subTier as an integrator-set band in 0–99.
+const MAX_BAND = 99;
+
+/// The same number `CleanverseIdentityRegistry.jurisdiction` derives on-chain:
+/// `uint16(bytes2(group))`, i.e. the first two ASCII bytes big-endian, so "US" is
+/// 0x5553 = 21843.
+///
+/// This used to be a lookup table that answered 1 for "US", so the same country had
+/// three different numbers across the production registry (21843), this mirror (1) and
+/// a unit test (1). The field is dormant — Cleanverse leaves `group` empty, so every
+/// read is 0 today and Covenant's own gate treats 0 as unconstrained — but a mirror
+/// that disagrees with what it mirrors is a fault waiting for the day the field is
+/// populated.
 export function mapJurisdiction(group: string | undefined): number {
   if (!group) return 0;
-  const code = JURISDICTION_CODES[group.toUpperCase()];
-  if (code === undefined) {
-    console.warn(`covenant-relayer: unmapped Cleanverse jurisdiction group "${group}", defaulting to 0`);
-    return 0;
-  }
-  return code;
+  const bytes = Buffer.from(group.toUpperCase(), "ascii");
+  return ((bytes[0] ?? 0) << 8) | (bytes[1] ?? 0);
 }
 
 export function toOnchainIdentity(apass: ApassInfo | null, nowSeconds: number, ttlSeconds: number): OnchainIdentity {
   if (!apass) return { verified: false, tier: 0, subTier: 0, jurisdiction: 0, verifiedUntil: 0 };
 
   // `tier` arrives as a string ("50") and is assigned by Cleanverse; `subTier` is the
-  // integrator-set band Covenant actually prices on. Both are clamped rather than
-  // truncated so an unexpected upstream value can never wrap into a higher band.
-  const tier = clampByte(apass.tier);
-  const subTier = clampByte(apass.subTier);
+  // integrator-set band Covenant actually prices on. Anything outside 0–99 folds to 0
+  // — the same rule `CleanverseIdentityRegistry._toUint8` applies on-chain, so the
+  // mirror and the contract it mirrors refuse the same values.
+  const tier = toBand(apass.tier);
+  const subTier = toBand(apass.subTier);
 
   const jurisdiction = mapJurisdiction(apass.group);
 
@@ -46,8 +51,11 @@ export function toOnchainIdentity(apass: ApassInfo | null, nowSeconds: number, t
   return { verified, tier, subTier, jurisdiction, verifiedUntil };
 }
 
-function clampByte(value: string | number | undefined): number {
+/// Folds rather than clamps: an out-of-range band must read as "unpriceable", not as the
+/// nearest priceable value. Clamping 150 to 99 would have quietly landed it in the top
+/// band; folding it to 0 blocks origination, which is what the contract does.
+function toBand(value: string | number | undefined): number {
   const n = value !== undefined ? Number(value) : NaN;
-  if (!Number.isFinite(n)) return 0;
-  return Math.min(Math.max(Math.trunc(n), 0), MAX_UINT8);
+  if (!Number.isFinite(n) || n < 0 || n > MAX_BAND) return 0;
+  return Math.trunc(n);
 }

relayer/src/mapping.ts

@@ -38,6 +38,9 @@ contract IdentityRegistry is Ownable, IIdentityRegistry {
     );
     event RelayerChanged(address indexed relayer);
 
+    /// Cleanverse documents subTier as an integrator-set band in 0–99.
+    uint8 internal constant MAX_SUBTIER = 99;
+
     error NotRelayer();
     error ZeroRelayer();
 
@@ -126,8 +129,18 @@ contract IdentityRegistry is Ownable, IIdentityRegistry {
         return _identity[subject].tier;
     }
 
+    /// Clamped exactly as `CleanverseIdentityRegistry._toUint8` clamps it, so the two
+    /// implementations of `IIdentityRegistry` answer the same question the same way.
+    ///
+    /// They did not agree before this: production folds anything above 99 to 0 and
+    /// blocks pricing, while this mirror returned it verbatim — so an out-of-spec
+    /// subTier of 150 was refused in production and priced at the top band here. Not
+    /// exploitable, since only the trusted relayer writes, but two implementations of
+    /// one interface disagreeing about a value is how a devnet test comes to prove
+    /// something production does not do.
     function subTier(address subject) external view returns (uint8) {
-        return _identity[subject].subTier;
+        uint8 value = _identity[subject].subTier;
+        return value > MAX_SUBTIER ? 0 : value;
     }
 
     function jurisdiction(address subject) external view returns (uint16) {

src/IdentityRegistry.sol

@@ -142,6 +142,10 @@ contract FuzzTest is CovenantTestBase {
     /// buying a guaranteed loss, and the supplier would be borrowing at a negative rate.
     function testFuzz_advanceNeverExceedsFace(uint96 faceValue, uint8 subTier) public {
         faceValue = uint96(bound(faceValue, 1e6, 1_000_000e6));
+        // 0–99 is the documented domain of subTier. Fuzzing it over the whole uint8 was
+        // asking the registry to price a value Cleanverse cannot issue, which both
+        // registries now answer with 0.
+        subTier = uint8(bound(subTier, 0, 99));
         vm.assume(note.advanceRateBpsFor(subTier) > 0);
 
         address obligor = makeAddr("fuzzObligor");
@@ -311,4 +315,21 @@ contract FuzzTest is CovenantTestBase {
         vm.expectRevert(IdentityRegistry.ZeroRelayer.selector);
         new IdentityRegistry(address(0));
     }
+
+    /// Both implementations of `IIdentityRegistry` must answer identically for a subTier
+    /// outside Cleanverse's documented 0–99: fold it to 0, which prices at nothing and
+    /// blocks origination. The devnet mirror used to return it verbatim while production
+    /// clamped, so a value refused on Monad was priced at the top band in tests.
+    function testFuzz_outOfRangeSubTierReadsAsZero(uint8 subTier) public {
+        address subject = makeAddr("clampProbe");
+        identityRegistry.adminSetIdentity(subject, true, 50, subTier, 1, uint64(block.timestamp + 365 days));
+
+        uint8 got = identityRegistry.subTier(subject);
+        if (subTier > 99) {
+            assertEq(got, 0, "out-of-range subTier must not be readable");
+            assertEq(note.advanceRateBpsFor(got), 0, "an unreadable identity must not be priced");
+        } else {
+            assertEq(got, subTier, "in-range subTier must round-trip");
+        }
+    }
 }