init: please read BRANCH_DIFF.md

Author: sjyim0513

.env.example

@@ -1,13 +1,36 @@
+# ── Root (hardhat: deploy, wire, demo tasks) ────────────────────────────────
+# Copy to .env (gitignored). This file is ONLY for the contract toolchain.
+# The worker and the indexer have their own: worker/.env and indexer/.env.
+#
+# See DEPLOYMENT.md for the full ordered sequence.
+
+# REQUIRED — the OWNER / deployer key (0x + 64 hex). This is what hardhat deploys from, and it is
+# the key that later calls `approvePacket` to release held packets.
+#
+# NOTE: worker/.env also has a variable named PRIVATE_KEY, but there it means the OPERATOR key.
+# Do not copy this file into worker/ — giving the worker the owner key would let it approve the
+# very packets it chose to withhold, which is exactly what the split exists to prevent.
 PRIVATE_KEY=
+
+# REQUIRED for a real deployment — the worker key's ADDRESS (not its private key).
+# Leave unset only for a throwaway demo: owner and operator then collapse onto the deployer and
+# the worker gains approval rights. The deploy script and `dvn:preflight` both warn about it.
+OPERATOR_ADDRESS=
+
+# Public defaults work but rate-limit. Use your own endpoints for anything sustained.
 RPC_URL_BASE_SEPOLIA=https://sepolia.base.org
 RPC_URL_OPTIMISM_SEPOLIA=https://sepolia.optimism.io
 
-# Populated after `lz:deploy` (Phase 8):
+# Populated AFTER deploying ComplianceDVN on each chain, and required BEFORE wiring.
+# `layerzero.config.ts` refuses to wire without them: wiring a placeholder succeeds silently and
+# then every message on that pathway is permanently unverifiable.
 DVN_BASE_SEPOLIA=
 DVN_OPTIMISM_SEPOLIA=
-# DVN operator / worker tuning:
-DVN_CONFIRMATIONS=5
-POLL_MS=15000
-CHECKPOINT_PATH=.context/dvn-checkpoint.json
-# Operator-controlled flagged address for the veto demo (address you hold the key for):
+
+# Optional — only read by the `demo:*` tasks, to show a vetoed transfer alongside a clean one.
+# An address you hold the key for. The worker has its own TEST_DENYLIST, which is the one that
+# actually causes the veto; this copy just drives the demo output.
 TEST_DENYLIST=
+
+# Worker tuning (DVN_CONFIRMATIONS, POLL_MS, CHECKPOINT_PATH, …) is NOT read here — it lives in
+# worker/.env. It used to be listed in this file, where setting it had no effect.

.gitignore

@@ -28,3 +28,6 @@ docs/superpowers/
 
 # presentation deck — kept local, not uploaded
 presentation/
+
+# worker runtime state (scan checkpoint, deferred queue, approvals) — per-deployment, not source
+worker/.context/

.prettierignore

@@ -17,5 +17,6 @@ package.json
 # Generated deployment artifacts (ABIs, solcInputs) — not hand-authored source.
 deployments/
 
-# Standalone Node 20 worker package: formatted via its own toolchain, not the root.
-worker/
+# Standalone Node 20 packages: formatted via their own toolchains, not the root.
+worker/
+indexer/

BRANCH_DIFF.md

@@ -0,0 +1,233 @@
+# Deployment — testnet
+
+Ordered sequence for bringing up the contracts, the indexer, and the worker. The order matters:
+each step produces a value the next one needs, and two of the steps are hard to undo.
+
+For day-2 operations (alerts, key rotation, recovery) see [worker/RUNBOOK.md](worker/RUNBOOK.md).
+
+## Keys
+
+Three distinct keys. Keeping them separate is not hygiene, it is the design:
+
+| Key                  | Held by             | Purpose                                                     | Must be funded   |
+| -------------------- | ------------------- | ----------------------------------------------------------- | ---------------- |
+| **owner / deployer** | a human             | deploys, and calls `approvePacket` to release held packets  | yes, both chains |
+| **operator**         | the worker process  | `submitVerification`, `commitVerification`, `recordVerdict` | yes, both chains |
+| **feed signer**      | the indexer process | signs published feeds                                       | no               |
+
+`approvePacket` is `onlyOwner` precisely so the worker cannot release the packets it chose to
+withhold. If owner and operator are the same key, that protection is gone — the worker could
+approve its own holds. The deploy script warns when they collapse.
+
+The owner key belongs in the CLI environment as `OWNER_PRIVATE_KEY`, **never** in the worker's
+environment.
+
+## 1. Root environment
+
+```bash
+cp .env.example .env
+```
+
+Set in `.env`:
+
+- `PRIVATE_KEY` — the **owner/deployer** key (this is what hardhat deploys from)
+- `OPERATOR_ADDRESS` — the worker key's _address_ (not its private key)
+- `RPC_URL_BASE_SEPOLIA`, `RPC_URL_OPTIMISM_SEPOLIA` — override the public defaults if you have
+  your own endpoints; public RPCs rate-limit and the indexer polls continuously
+
+Leave `DVN_BASE_SEPOLIA` and `DVN_OPTIMISM_SEPOLIA` empty for now — they are outputs of step 3.
+
+## 2. Preflight
+
+```bash
+npx hardhat dvn:preflight --network base-sepolia
+```
+
+```bash
+npx hardhat dvn:preflight --network optimism-sepolia
+```
+
+Checks the signer resolves, the RPC answers, the deployer is funded, the ReceiveUln is known, and
+whether an existing deployment is compatible. Sends no transactions. Fix every `ERROR` and read
+every `WARN` before continuing.
+
+## 3. Deploy the DVN
+
+Both chains. `OPERATOR_ADDRESS` must be set or owner and operator collapse.
+
+```bash
+npx hardhat deploy --network base-sepolia --tags ComplianceDVN
+```
+
+```bash
+npx hardhat deploy --network optimism-sepolia --tags ComplianceDVN
+```
+
+Then put the two addresses into `.env` as `DVN_BASE_SEPOLIA` and `DVN_OPTIMISM_SEPOLIA`.
+
+> A previously deployed ComplianceDVN cannot be reused. `submitVerification` gained verdict
+> parameters and the contract is not upgradeable, so the old address exposes a different ABI.
+> `dvn:preflight` detects this and says so.
+
+## 4. Wire the pathway
+
+This is the step that tells the ULN which DVN each pathway **requires**.
+
+```bash
+npx hardhat lz:oapp:wire --oapp-config layerzero.config.ts
+```
+
+`layerzero.config.ts` throws if either `DVN_*` is unset rather than defaulting to a placeholder —
+wiring a zero address succeeds silently and then every message on that pathway is permanently
+unverifiable, because the required DVN has no code to verify with.
+
+Confirm both sides:
+
+```bash
+npx hardhat dvn:status --network base-sepolia
+```
+
+Check `operator` is the worker address and `owner` is yours.
+
+## 5. Indexer
+
+```bash
+cd indexer
+cp .env.example .env
+```
+
+Set:
+
+- `FEED_SIGNING_KEY` — a fresh key, used only for signing. Note its **address**; the worker needs it.
+- `DVN_BASE_SEPOLIA`, `DVN_OPTIMISM_SEPOLIA` — from step 3
+- `TRACKED_TOKENS` — the ERC-20s whose transfers build the graph. **Empty means no edges**, so the
+  feed will be valid, signed, and empty.
+- `TOKEN_MINIMUMS` — `chain:token:minValue` per token, in the token's smallest unit. **Without an
+  entry a token never produces an inbound label**, so leaving this empty turns
+  `sanctions_1hop_inbound` off entirely. Outbound labels are unaffected.
+- `POLICY_VERSION` — must equal the worker's `POLICY_VERSION` in `worker/assess/policy.ts` (currently `1`)
+
+```bash
+docker compose up -d
+```
+
+Migrations run at boot. Verify:
+
+```bash
+curl -s localhost:9091/feed/latest.json | head -c 400
+```
+
+A `503 no feed published yet` is expected until the first build (`FEED_REBUILD_MS`, default 10 min).
+Check the logs for the boot warnings — they name any tracked token missing a threshold.
+
+Get the signer address for the next step:
+
+```bash
+docker compose logs indexer | grep -i "indexer feed\|signer"
+```
+
+## 6. Worker
+
+```bash
+cd worker
+cp .env.example .env
+```
+
+Set:
+
+- `OPERATOR_PRIVATE_KEY` — the **operator** key (funded on both chains). The name differs from
+  the root `.env` deliberately: the worker rejects a bare `PRIVATE_KEY` and explains why, so
+  copying the root file here fails loudly instead of granting owner rights.
+- `DVN_BASE_SEPOLIA`, `DVN_OPTIMISM_SEPOLIA` — from step 3
+- `INDEXER_FEED_URL` — e.g. `http://<indexer-host>:9091/feed/latest.json`
+- `INDEXER_SIGNERS` — the indexer's signer **address**. The worker refuses to boot with a feed URL
+  and no allowlist: ingesting unverified labels is worse than having none.
+- `EMIT_VERDICT_EVENTS` — `block` by default, which means each veto costs a `recordVerdict`
+  transaction. Set it empty to record only `allow` (which rides along on `submitVerification` for
+  free).
+- `TEST_DENYLIST` — an address you hold a key for, if you want to demo a veto
+
+Do **not** set `OWNER_PRIVATE_KEY` here.
+
+```bash
+pnpm start
+```
+
+```bash
+curl -s localhost:9090/readyz
+```
+
+The worker refuses to verify anything until it has a fresh risk store, so `readyz` failing at
+first is the fail-closed design working, not a fault.
+
+## 7. Smoke test
+
+Send a clean transfer and watch it settle. `demo:send` is the convenience wrapper:
+
+```bash
+npx hardhat demo:send --network base-sepolia --dst opt --to 0x<recipient> --amount 1
+```
+
+Or the full LayerZero task, which takes explicit eids rather than a network:
+
+```bash
+npx hardhat lz:oft:send --src-eid 40245 --dst-eid 40232 --to 0x<recipient> --amount 1
+```
+
+The worker log should show `VERIFY submitted` then `COMMIT driven`. Or screen a specific
+transaction without sending:
+
+```bash
+pnpm cli verify baseSepolia 0x<txhash> --dry-run
+```
+
+Then exercise a veto by putting a held address in `TEST_DENYLIST` and sending from it — expect
+`VETO — withholding verification` and no delivery.
+
+To exercise the manual-review path, set `OWNER_PRIVATE_KEY` in your **shell** (not the worker's
+env) and:
+
+```bash
+pnpm cli pending
+```
+
+```bash
+pnpm cli approve optimismSepolia 0x<payloadHash>
+```
+
+## Cross-checks that bite later
+
+- **Operator gas on both chains.** `submitVerification` and `commitVerification` run on the
+  _destination_ chain, so a bidirectional pathway needs the operator funded on both.
+- **`POLICY_VERSION` must match** between worker code and indexer env. A mismatched feed is
+  rejected whole, not reconciled — scores computed under different weights are not comparable.
+- **Feed TTL vs rebuild interval.** `FEED_TTL_SEC` must exceed `FEED_REBUILD_MS` or a document can
+  expire before its replacement exists and screening flaps. Config enforces this.
+- **Staleness vs refresh.** `MAX_DENYLIST_STALENESS_MS >= DENYLIST_REFRESH_MS`, likewise enforced.
+- **`DEGRADED_MODE`.** Default `degrade` keeps verifying on OFAC/OpenSanctions alone when the feed
+  is unavailable. `halt` withholds everything instead. Decide deliberately.
+- **Sourcify v1 is in a brownout.** The indexer targets v2; if you point `VERIFIER_URL` at a
+  self-hosted instance, make sure it serves `/v2/contract/{chainId}/{address}`.
+
+## Dashboards
+
+For a local stack, the indexer's compose file brings up Prometheus and Grafana with both dashboards
+and both datasources already provisioned:
+
+```bash
+docker compose --profile observability up -d
+```
+
+Grafana on <http://localhost:3000> (loopback only, anonymous viewer). See
+[indexer/README.md](indexer/README.md) for what the panels mean.
+
+To wire them into existing monitoring instead, import:
+
+- `worker/deploy/grafana-dashboard.json` — Prometheus only
+- `indexer/deploy/grafana-dashboard.json` — needs both Prometheus and the indexer's Postgres;
+  the audit trail lives in Postgres and is deliberately not exported as metrics
+
+Both pin their datasource variables to the uids `dvn-prometheus` / `dvn-postgres`; if yours are
+named differently, repoint the variable once at the top of the dashboard.
+
+Alerts: `worker/deploy/k8s/prometheusrule.yaml`.

DEPLOYMENT.md

@@ -19,7 +19,40 @@ contract ComplianceDVN is ILayerZeroDVN, Ownable {
     event ReceiveUlnSet(address receiveUln);
     event FeeSet(uint256 fee);
 
+    /// @notice A held packet cleared for verification by the owner. Deliberately owner-only:
+    ///         the worker holds only the operator key, so it cannot approve its own holds.
+    event PacketApproved(bytes32 indexed payloadHash, address approver);
+
+    /// @notice The risk decision behind a packet's outcome.
+    /// @param payloadHash the packet this verdict is about
+    /// @param action ACTION_* below
+    /// @param score 0-100 risk score the action was derived from
+    /// @param reasonMask bitmask of reason codes; bit assignments are append-only and
+    ///        documented in the worker's `assess/verdict.ts`
+    /// @param evidenceHash keccak256 of the canonical evidence document held off-chain
+    event RiskVerdict(
+        bytes32 indexed payloadHash,
+        uint8 action,
+        uint16 score,
+        uint256 reasonMask,
+        bytes32 evidenceHash
+    );
+
+    /// @dev Action codes. These are part of the event ABI: an indexer decoding old logs relies
+    ///      on them, so the numbering is permanent. Kept in sync with the worker's ACTION_CODES.
+    uint8 public constant ACTION_ALLOW = 0;
+    uint8 public constant ACTION_DELAY = 1;
+    uint8 public constant ACTION_MANUAL_REVIEW = 2;
+    uint8 public constant ACTION_BLOCK = 3;
+
     error NotOperator();
+    error UnknownAction(uint8 action);
+    /// @dev Submitting a verification asserts the packet was allowed; any other action would be
+    ///      a self-contradicting record.
+    error VerificationRequiresAllow(uint8 action);
+    /// @dev An allow rides along on `submitVerification`, so recording one separately would
+    ///      double-report the same outcome.
+    error AllowNotSeparatelyRecorded();
 
     modifier onlyOperator() {
         if (msg.sender != operator) revert NotOperator();
@@ -52,12 +85,49 @@ contract ComplianceDVN is ILayerZeroDVN, Ownable {
         return fee;
     }
 
+    /// @notice Attest a packet and record the risk verdict that permitted it, in one call.
+    /// @dev The verdict rides along at no extra transaction cost, so an allowed packet always
+    ///      carries an auditable reason for having been allowed. `action` must be ACTION_ALLOW:
+    ///      a packet that was blocked or held cannot also have been verified. An owner-approved
+    ///      release is reported as ACTION_ALLOW too — a human allowed it — with the reason mask
+    ///      still carrying why it had been held.
     function submitVerification(
         bytes calldata packetHeader,
         bytes32 payloadHash,
-        uint64 confirmations
+        uint64 confirmations,
+        uint8 action,
+        uint16 score,
+        uint256 reasonMask,
+        bytes32 evidenceHash
     ) external onlyOperator {
+        if (action != ACTION_ALLOW) revert VerificationRequiresAllow(action);
         IReceiveUlnE2(receiveUln).verify(packetHeader, payloadHash, confirmations);
+        emit RiskVerdict(payloadHash, action, score, reasonMask, evidenceHash);
+    }
+
+    /// @notice Record a verdict for a packet that was NOT verified.
+    /// @dev Withholding the attestation is what actually stops the packet; this only leaves the
+    ///      audit trail. It is therefore best-effort by design — the worker treats a failure
+    ///      here as a lost record, never as a failure to enforce.
+    function recordVerdict(
+        bytes32 payloadHash,
+        uint8 action,
+        uint16 score,
+        uint256 reasonMask,
+        bytes32 evidenceHash
+    ) external onlyOperator {
+        if (action > ACTION_BLOCK) revert UnknownAction(action);
+        if (action == ACTION_ALLOW) revert AllowNotSeparatelyRecorded();
+        emit RiskVerdict(payloadHash, action, score, reasonMask, evidenceHash);
+    }
+
+    /// @notice Clear a packet the worker withheld for manual review.
+    /// @dev Emits only; no storage. The worker observes `PacketApproved` and releases the
+    ///      packet from its local deferred queue. Approval is a human override of a risk
+    ///      verdict, so it is separated from the operator key by design — a compromised or
+    ///      buggy worker cannot approve the packets it chose to hold.
+    function approvePacket(bytes32 payloadHash) external onlyOwner {
+        emit PacketApproved(payloadHash, msg.sender);
     }
 
     function setOperator(address _operator) external onlyOwner {