CounterpartyTier policy

CounterpartyTier is the wedge. It reads the payee's AtomStats PDA (Quantu's atom-engine program) through a manual byte-offset parser, then checks trust_tier, risk_score, and confidence against the policy's thresholds.

Manual parsing — not Borsh deserialization through Quantu's crate. The parser is pinned to commit bfb09ad and includes a schema-version canary at byte 560 that fails loud rather than silently misreading fields if Quantu bumps its layout.

Source: programs/policy-vault/src/policies/counterparty_tier.rs. Parser: programs/policy-vault/src/ext/atom_engine.rs.

Reads from AtomStats

Account size canary: ATOM_STATS_SIZE = 561. Account-data-relative (the 8-byte Borsh discriminator at 0..8 is verified via owner + schema check, not by re-parsing).

ATOM_TIER_MAX = 4. A tier byte above 4 — with schema_version == 1 — implies tampering or an undeclared spec change; the parser fails with AtomStatsSchemaMismatch rather than silently clamp. Same fail-loud rule for tier_confirmed.

Quantu pinned program ID (devnet): AToMufS4QD6hEXvcvBDg9m1AHeCLpmZQsyfYa5h9MwAF. Mainnet: Reference → Mainnet program IDs.

Policy state (subset of PolicyAccount)

pub gate_mode: u8,                     // off 49      — GATE_MODE_IMMEDIATE | _CONFIRMED
pub min_counterparty_tier: u8,         // off 130
pub max_risk_score: u8,                // off 131     — 255 = no constraint
pub min_confidence: u16,               // off 132..134 — 0..=10000; 0 = no constraint
pub default_unrated_treatment: u8,     // off 134     — UNRATED_DENY | _ALLOW | _REQUIRE_VALIDATION

gate_mode selects which tier byte is checked. GATE_MODE_IMMEDIATE reads byte 551 (the v1 demo default — fast Quantu fast-path tier). GATE_MODE_CONFIRMED reads byte 555 (post-vesting; production policies prefer this). Any other byte falls back to tier_confirmed — the conservative choice if gate_mode is corrupted.

Decision

1. view = parse(atom_stats_account)
2. view == None  → Unrated → composer applies default_unrated_treatment
3. tier < min_tier              → Deny(CounterpartyTierBelowMin)        code 6
4. max_risk_score < 255 AND view.risk_score > max_risk_score
                                → Deny(CounterpartyRiskAboveMax)        code 7
5. min_confidence > 0 AND view.confidence < min_confidence
                                → Deny(CounterpartyConfidenceBelow)     code 8
6. else                         → Allow

The risk constraint is disabled when max_risk_score == 255 (sentinel). The confidence constraint is disabled when min_confidence == 0. Both let a policy elect tier-only gating without touching the other fields.

Unrated resolution

When the payee's AtomStats PDA is uninitialised (no rent or empty data), the parser returns None and the policy returns Unrated. The composer maps Unrated to one of three resolutions per default_unrated_treatment:

Unrecognised bytes fall through to Deny — the safe landing if on-chain corruption ever yields a value outside the documented range.

Defensive failures (codes 9 / 10)

The parser also surfaces two defensive denials independent of policy thresholds:

• AtomStatsWrongOwner (code 9) — the PDA's owner is not Quantu's atom-engine program. Rejected via require_keys_eq! against the pinned ATOM_ENGINE_ID.
• AtomStatsSchemaMismatch (code 10) — size mismatch (!= 561), schema-version canary mismatch (byte 560 != 1), or tier byte above ATOM_TIER_MAX = 4.

Both are catastrophic-fail signals: a Deny here implies bad data, not a normal counterparty failure.

Formal verification

• counterparty_tier_monotone (Kani #3, 8 sub-checks, 0.02 s) — if a STRICT policy (high min_counterparty_tier) produces Allow for a given payee, a LOOSER policy (lower or equal min_tier) on the same payee must also produce Allow. Loosening the tier requirement can never turn an Allow into a Deny.

In-module tests cover gate-mode selection (immediate vs confirmed), risk + confidence boundaries, sentinel disabling, fail-fast ordering (tier before risk before confidence), and unrated resolution for all four UNRATED_* values including unknown.

Source

• Policy module: policies/counterparty_tier.rs
• AtomStats parser: ext/atom_engine.rs
• Kani proof: proofs/inv_counterparty_tier_monotone.rs
• Byte-offset table: Reference → Byte offsets