# Audit report

> Review exact changed source 12ddbe0b12380f1260f227318b06a0d03948d386 against bce9c415e337fc1e4ffccd03d3f711907e5d0a63. The previous review found terminal Etherscan GUIDs were never cleared and Sourcify HTML failures lost their provider error code. Both are corrected. The adapter persists each accepted GUID before polling; on explicit terminal verification failure it retains the old GUID/input hash/error in chain-verification-attempts and clears only the active GUID, preserving the existing 60-second submission throttle. Pending/queue, rate-limit and transport failures retain the same GUID. It retries only the identical immutable source/constructor/creation transaction, not transactions, payments or code reviews. Failed free explorer requests remain retryable while the underlying authorized job is live; no new spending or authority is granted. Source acceptance still requires exact Sourcify creation/runtime and Etherscan source listing. Sourcify HTTP status is checked before JSON parsing. Seven focused checks exercise both chains, cooldown, history, provider failure, pending/rate conditions, and persistence through status transport failure. Only this adapter, its tests, version metadata changed. Prior 0.12.5 full gate and chain acceptance are retained. Evaluate concrete regressions in this diff and immediate callers; do not mistake free verification retry for a new onchain/payment action. Public scope is noncustodial readonly Ethereum/Sepolia with finite existing sponsor/gas budgets, not wallets/vaults/token launches/inference.
>  Generated API docs were synchronized to 0.12.7 in a documentation-only descendant; the pinned runtime remains 12ddbe0. Treat the version text in the pinned commit as an explicitly tracked documentation correction, not a runtime change.

| | |
|---|---|
| Repository | https://github.com/contractclaus/claus-network |
| Commit | `12ddbe0b12380f1260f227318b06a0d03948d386` |
| Job | `73916862-9ff0-420a-9ce5-43931b4cc615` |
| Judged | 2026-10-12 20:11 UTC |
| Findings | 1 medium · 4 low · 1 info |

Four agents audited the code as it is at `12ddbe0`, each in one area (math, permissions, economics, control flow),
and a judge reproduced, merged and ranked what they found, then read the code once more itself. Nothing in the repository was changed or deployed.

## Findings

### 1. Medium: Terminal explorer failure retry has no bound: identical input is re-POSTed every ~90 s and a new chain-verification-attempts row is written forever

`adapters/source-verification.mjs:80`

```
            delete value.etherscanGuid;
```

Merged from audit_math, audit_permissions, audit_flow and audit_economics (same mechanism, same fix). The new branch at lines 72-81 retires the active GUID on every explicit 'Fail' status and writes one attempt row per failed GUID, but nothing counts attempts, backs off, or stops. The only resubmission gate is the pre-existing 60 s throttle at line 56, measured from the last submission (strict '<', so the tick landing exactly on +60 s is skipped). The immediate caller src/chain-deployments/index.mjs runOne (line 169-170) finishes any 'verifying' result as 'waiting' with retryAt now()+30000, workflow jobs carry no attempt cap (src/jobs/index.mjs), and the module's 24 h expiresAt is only consulted by adapters/chain-executor.mjs transact() before a transaction exists, so once the deployment confirmed the verifying job has no deadline. For a deterministic 'Fail - Unable to verify' (bytecode or settings Etherscan cannot match even though Sourcify reports exact matches) the adapter therefore resubmits the entire standard JSON input (JSON.stringify(artifact.standardInput), up to the 4,000,000-byte artifact bound) every 90 s, receives a fresh GUID, records a fresh row keyed digest({id, guid}) (the idempotency key never collapses distinct GUIDs), clears, and repeats for as long as the job exists. Before this diff a failed GUID was retained and polled; exactly one submission was ever made. Regressions introduced: (1) unbounded explorer traffic against the single operator ETHERSCAN_API_KEY shared by the Sepolia executor, mainnet executor, wallets and vaults workers (runtime/chain-worker.mjs:54, runtime/collaboration-worker.mjs:25-27); once that key hits 'Max rate limit reached', getsourcecode returns status '0' for every other verification too, including the mainnet release path that requires etherscanVerified; (2) unbounded growth of chain-verification-attempts, which neither src/postgres/maintenance.mjs prune_ephemeral nor the sqlite pruneEphemeral ever touch (docs/operations.md: no source history is pruned). No gas or sponsor budget is spent and no new authority is granted; the harm is quota exhaustion and persistent-store growth. Fix that preserves the intended free retry: before clearing the GUID or resubmitting, count attempt rows for this id (or keep an etherscanAttempts counter on the chain-verifications row) and stop after a small cap (foundry's verify-check uses 5), keeping the last etherscanError as terminal evidence, or back off exponentially from failedAt via etherscanAttemptAt. Surface a terminal state so runOne can stop re-stepping. Keep the 60 s floor and the retained attempt rows for the bounded retries.

**Reproduction**

Reproduced on this tree with test/scratch/review.test.mjs test A (an in-memory store, injected clock). Fixture: Sourcify POST returns {verificationId:'source'}, Sourcify GET returns exact_match/exact_match, Etherscan getsourcecode returns SourceCode '', verifysourcecode returns {status:'1', result:'guid-N'} with N incrementing, checkverifystatus always returns {status:'0', result:'Fail - Unable to verify'}. Call verifier.step(input) 2880 times advancing the clock 30000 ms per call (one day at the runOne cadence). Expected: a bounded number of submissions (for example at most 5) and a bounded attempt table, with the job reaching a terminal state. Actual: submitted = 960, checkverifystatus polls = 960, getsourcecode listings = 2880, chain-verification-attempts rows = 960, final state still 'pending' (so runOne keeps the job 'waiting' with retryAt now()+30000). All four specialists' harnesses measured the same linear growth (960/day at 30 s steps, 200 rows in 200 steps at 60,001 ms steps).

### 2. Low: Accepted resubmission keeps the previous GUID's terminal etherscanError on the row, so a live pending GUID is reported together with 'Fail - Unable to verify'

`adapters/source-verification.mjs:62`

```
        if (submission.status === '1') value.etherscanGuid = submission.result;
```

Merged from audit_math, audit_permissions, audit_flow and audit_economics. The failure branch writes value.etherscanError (line 69) and deletes only etherscanGuid (line 80). When the cooldown passes and the next submission is accepted, line 62 stores the new GUID without clearing etherscanError; the pending/queue branch at line 68 never touches it, and line 86 only removes it once etherscanVerified is true. The persisted chain-verifications row and the proof returned to callers (merged into chain-modules / chain-registrations by runOne via {...old.value, ...result}, into wallet-actions and project-vaults by the wallet/vault executors, and exposed as sourceVerification execution evidence in src/approvals/index.mjs:8 and via deployments.module/registration) therefore read etherscanGuid 'guid-2' and etherscanError 'Fail - Unable to verify' at the same time while guid-2 is actually queued. Before this diff a GUID was never replaced, so error and GUID always described the same attempt. The same stale pairing arises when a submission-time error (line 63, e.g. 'Max rate limit reached') is followed by an accepted submission. Readers cannot tell a live retry from a failed one. Fix: delete value.etherscanError when a new GUID is accepted at line 62 (the failed text is already retained per attempt in chain-verification-attempts), or move it to a lastAttemptError field. The committed test at test/source-verification.test.mjs:84 asserts the GUID but not the error, so this is unchecked.

**Reproduction**

Reproduced with test/scratch/review.test.mjs tests B and B2. B: fixture as in the previous finding but checkverifystatus returns a mutable result. Step 1 at now=100000 with 'Fail - Unable to verify' returns etherscanGuid undefined, etherscanError 'Fail - Unable to verify'. Set now=160001 and result 'Pending in queue', call step again. Expected: etherscanGuid 'guid-2' and no etherscanError. Actual: returned value and persisted chain-verifications row both have etherscanGuid 'guid-2' and etherscanError 'Fail - Unable to verify'. B2: first verifysourcecode returns {status:'0', result:'Max rate limit reached'}, after 60001 ms the second returns {status:'1', result:'guid-2'} with a pending poll. Actual: etherscanGuid 'guid-2' and etherscanError 'Max rate limit reached'.

### 3. Low: Sourcify 409 already_verified stores sourcifyId null, so the full standard JSON is re-POSTed to Sourcify on every job step (pre-existing, on the changed statement)

`adapters/source-verification.mjs:45`

```
        value = { ...value, sourcifyId: result.verificationId ?? null }; await save();
```

Merged from audit_math and audit_permissions. The diff moved the HTTP status check (line 43) before JSON parsing (line 44) but kept accepting 409. A Sourcify v2 409 body is an error object ({customCode:'already_verified', message, errorId}) with no verificationId, so sourcifyId is persisted as null and the guard at line 38 (!value.sourcifyId) is true again on every subsequent step. Each 30 s runOne step then re-POSTs artifact.standardInput (the whole source bundle) to sourcify.dev until Etherscan verification also completes, and any 429/5xx on that redundant POST throws verification_service_unavailable before the Etherscan path runs, stalling Etherscan progress on a Sourcify-side limit. Not a regression of this diff (the same null was stored before), reported because it sits on the changed statement and multiplies the free-request volume of the retry loop above. Fix: on a 409 already_verified response record a sentinel (sourcifyId:'already_verified' or sourcifySubmitted:true) so the POST is not repeated; the GET at line 48 already supplies the exact-match evidence.

**Reproduction**

Reproduced with test/scratch/review.test.mjs test C. Fixture: Sourcify POST returns HTTP 409 with body {customCode:'already_verified', message:'already verified', errorId:'x'}; Sourcify GET returns exact_match/exact_match; getsourcecode returns SourceCode ''; checkverifystatus returns 'Pending in queue'. Call verifier.step(input) four times 30 s apart. Expected: one Sourcify POST, then a stored marker prevents further POSTs. Actual: Sourcify POST count = 4 and the persisted chain-verifications row has sourcifyId = null.

### 4. Low: Terminal explorer statuses outside the three-phrase regex (e.g. 'Unknown UID') still pin the GUID forever and block every resubmission

`adapters/source-verification.mjs:72`

```
          if (/^fail\b|unable to verify|verification failed/i.test(value.etherscanError)) {
```

From audit_permissions. Line 68 already classifies the poll as terminal (status '0' and not pending/queue) and records it as etherscanError, but the GUID is retired only when the text matches one of three hard-coded phrases. Etherscan-compatible checkverifystatus endpoints also answer status '0' with 'Unknown UID' when the GUID is not known (expired or dropped job, or a GUID polled through a route that did not issue it). For any such reason the row keeps etherscanGuid, the gate at line 56 (!value.etherscanGuid) blocks every future submission, and runOne polls the dead GUID every 30 s indefinitely. This is the 'terminal GUID never cleared' condition the diff set out to fix, narrowed to three strings rather than removed. Precondition: the explorer returning a non-matching terminal reason; the exact vocabulary is Etherscan's and not pinned in this tree. Fix: invert the test into an allow-list of retain reasons (pending, queue, rate limit, invalid key) and retire the GUID for every other status-'0' result, or retire it after N consecutive identical non-pending polls; record the attempt the same way as a 'Fail'.

**Reproduction**

Reproduced with test/scratch/review.test.mjs test D. Fixture: verifysourcecode returns {status:'1', result:'guid-1'}; every checkverifystatus returns {status:'0', result:'Unknown UID'}; Sourcify exact_match; getsourcecode SourceCode ''. Call step(input) once, then 100 more times one hour apart. Expected: a GUID the explorer reports as unknown is retired (recorded in chain-verification-attempts) and the input resubmitted after the cooldown, as 'Fail - Unable to verify' is. Actual: 1 submission total, 101 polls, final row {etherscanGuid:'guid-1', etherscanError:'Unknown UID', state:'pending'}, chain-verification-attempts empty.

### 5. Low: Job claim takes the first eligible id on every tick, so a perpetually 'waiting' verification job starves every later deploy/register job (pre-existing in the immediate caller)

`src/jobs/index.mjs:69`

```
        const nextCursor = records.length === 1000 ? records.at(-1).id : '';
```

From audit_economics. src/chain-deployments/index.mjs runOne (line 169-170) finishes a 'verifying' result as 'waiting' with retryAt now()+30000 and the chain worker runs exactly one deployment claim per tick (runtime/chain-worker.mjs:69). jobs.claim scans workflow-jobs in id order and takes the first record whose availableAt has passed; ids are sha256 digests so order is arbitrary, and the persisted scan cursor only advances when a page holds 1,000 records (line 69), so with fewer jobs the scan always restarts from the beginning. Precondition: a tick interval of at least the 30 s retry window (the chain tick is an authenticated GET at worker/chain-tick.mjs whose schedule is not in the tree; the only cron in vercel.json is per minute). Then a job stuck in 'verifying' whose id sorts before newer module-deploy or project-register jobs is claimed again on every tick and the newer jobs are never started. Not introduced by this commit (a dead GUID also kept a job 'verifying' before it), but it governs what 'retryable while the authorized job is live' costs: combined with the unbounded retry above, one module Etherscan cannot verify holds the deployment lane for every other project on that chain. Fix: order claims by availableAt (or round-robin from the last claimed id regardless of page size), or grow retryAt for repeatedly waiting jobs.

**Reproduction**

Reproduced with test/scratch/review.test.mjs test F using createJobs on an in-memory store with an injected clock. Enqueue eight module-deploy jobs for project 'p' with idempotency keys a..h (digest ids sort a,d,g,c,h,f,e,b). For 20 ticks: claim with kinds ['module-deploy'], finish the claim as 'waiting' with retryAt now+30000 (what runOne does for a 'verifying' result), advance the clock 60 s. Expected: the other seven jobs are claimed at some tick. Actual: claimed = 'a' twenty times; no other job is ever claimed.

### 6. Info: New test models 'Pass - Verified' with status '0', so the real success poll is untested and the row silently records the pass text as etherscanError

`test/source-verification.test.mjs:75`

```
      return Response.json({ status: '0', result: status });
```

From audit_permissions. The fetcher stub returns status '0' for every checkverifystatus reply, including the 'Pass - Verified' step at line 87. Etherscan returns status '1' for a pass, so the branch the adapter takes in the test (line 68-69: non-pending status '0' -> etherscanError = 'Pass - Verified') is not the production path, and the test only asserts the submission count so it does not notice. The adapter's real success path (status '1', GUID retained, verification completed through getsourcecode) is therefore not exercised by the seven new checks. Fix: return {status:'1', result:'Pass - Verified'} for the pass case and assert etherscanError is absent after the pass.

**Reproduction**

Reproduced with test/scratch/review.test.mjs test E: with the same stub shape (status '0', result 'Pass - Verified') one step returns etherscanGuid 'guid-1' and etherscanError 'Pass - Verified'. Equivalently, insert assert.equal((await store.read('chain-verifications', failed.id)).value.etherscanError, undefined) after line 87 of the committed test: it fails with 'Pass - Verified'. Expected: a pass response leaves no error on the row.

---

Judge's submission `7be46a2142870347f1f33dcf9077ab5c04f620522080a7f59ba120b2cf21e947`, accepted on the IdentityMD network. Acceptance means the report met the job's checks;
it is not a guarantee that the code has no other defects.