feat(app): compliance surface

[luchobonatti]

Summary

Closes #194

The Compliance tab reads a target address's allowlist, freeze and share state, and lets the compliance authorities allowlist it and intervene on its shares.

Changes

• Target address input; its allowlist, frozen flag, balance and frozen shares are read before any action
• Allow and remove on the share token's identity verifier, available only to that verifier's admin
• Freeze and unfreeze the address, freeze and unfreeze part of its shares, and forced transfer, each showing the resulting state before signing
• An action that targets the vault itself needs a confirmation before signing
• Refused actions name the contract error
• The investor allowance is read at the verifier the share token points to; a failed read is retried
• recover_balance is not offered: the identity verifier has no recovery target, so it always fails

Acceptance criteria

• Target address's current allowlist and frozen state shown before any action
• Each action shows its resulting state before a signature is requested
• A refused action names the contract error

Test plan

Automated tests

npm run test — 1546 passing.

Manual verification

1. On a local network, open /admin/compliance as compliance and enter an investor address: its allowlist, frozen state and shares.
2. Freeze part of its shares: the resulting frozen amount shows before signing.

Breaking changes

None.

Checklist

• Self-reviewed my own diff

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
strata-vault-kit-app	Ready	Preview	Oct 14, 2026 2:57pm UTC

[Copilot]

🔵 Needs a closer look

It introduces a privileged compliance surface performing irreversible share interventions (freezes, forced transfers) plus new on-chain admin-reading and authorization logic, which warrants human review despite the strong test coverage.

1 open finding

• Duplicate tile label lists can drift out of sync · New

What changed in this PR

This PR adds the Compliance admin surface (closing #194), giving the compliance and identity‑verifier‑admin authorities a screen to read a target address's allowlist/freeze/share state and act on it (allowlist add/remove, address freeze/unfreeze, partial share freeze/unfreeze, and forced transfer). Each action previews its resulting state before signing, names the contract error on refusal, and requires an extra confirmation when the action targets the vault itself. Supporting this, shared admin‑rail helpers are extracted from governance.ts into actions.ts, useIsAllowed now resolves the verifier dynamically from the share token (with retry), useAdminAuthority reads the verifier's on‑chain admin via a new readContractAdmin, and the client layer gains per‑address verifier reader/writer factories.

Changes:

• New compliance surface: compliance.ts action/tile builders, ComplianceSection UI, useComplianceState/useComplianceTransactions hooks, and TransactionModal copy + error‑code reasons (300/301/303/2001).
• Shared refactor: Built/BuiltSpec/Inputs/confirmation/confirmKey/parseAccount/clearConfirmations/withInput moved to actions.ts; new useRailInputs hook; useAdminAuthority gains verifierAdminUnknown and an identity-verifier admin role surface.
• Lib support: readContractAdmin + TTL‑0 handling in readContract.ts, addAmounts/subtractAmounts in format.ts, optional signer on connectIdentityVerifier.

File	Description
app/​src/​pages/​compliance.ts	Core compliance action/tile builders (allow, freeze, shares, forced transfer, vault confirmation)
app/​src/​pages/​actions.ts	Extracted shared rail helpers now reused by governance and compliance
app/​src/​pages/​governance.ts	Refactored to consume the shared helpers from actions.ts
app/​src/​hooks/​useComplianceState.ts	Reads target allowlist/frozen/balance/frozen-shares and destination allowance
app/​src/​hooks/​useComplianceTransactions.ts	Admin write hooks for allow/freeze/forced-transfer with invalidation keys
app/​src/​hooks/​useIsAllowed.ts	Resolves verifier from the share token, with retry and unreadable handling
app/​src/​hooks/​useAdminAuthority.ts	Adds verifier-admin read, verifierAdminUnknown, and compliance surface role
app/​src/​hooks/​useRailInputs.ts	New hook centralizing rail input/confirmation state
app/​src/​config/​clients.ts	Per-address verifier reader/writer caches (identityVerifierAt, identityVerifierWriter)
app-lib/​readContract.ts	New readContractAdmin reading instance-storage admin; opt-in TTL-0-is-live flag
app-lib/​format.ts	addAmounts/subtractAmounts (floor-at-zero) helpers
app-lib/​contracts.ts	connectIdentityVerifier accepts an optional signer
app/​src/​components/​admin/​ComplianceSection.tsx /​ .module.css	New surface UI wiring reads, rail, target input, and modal
app/​src/​components/​vault/​TransactionModal.tsx	Compliance action copy and new refusal reasons
app/​src/​pages/​AdminPanel.tsx	Routes the compliance surface and threads verifierAdminUnknown
Multiple *.test.* files	Extensive new/updated unit coverage for the above

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.