docs/demo-auditor-review.md

1# Stages demonstration: auditor references and probe review
2
3Prepared locally on 2026-10-10. Reviewed the public `https://tokenize.caiborg.ai/stages.html`, its repository template and builder, the hostile-run producer, and the public measured datasets. Source baseline: `07ff13a`. This log records this task, separately from the earlier system-design reviews. The user explicitly requested local changes only. No deployment or new on-chain transactions were performed.
4
5## What “attacks” means here
6
7These are scripted negative integration tests that submit real transactions. They are meaningful evidence of how the supplied inputs were handled; their strength depends on which rule was actually reached.
8
9The producer is [ops/src/attacks.ts](../ops/src/attacks.ts). `land` constructs and signs a transaction, sets its first signer as fee payer, submits it with `skipPreflight: true`, and polls until confirmed or finalized. Expired blockhashes can trigger a retry. Skipping preflight makes a refusal publicly inspectable rather than leaving only a local simulation result.
10
11`attempt` retrieves the transaction, reads `meta.err` and execution logs, and accepts the test result only when the transaction failed **and the extracted reason contains the expected guard token**. This is substring matching, not full verification of every instruction or postcondition. In particular, `claim-as-owner` only requires `Constraint`, although its actual recorded error is `ConstraintSeeds`.
12
13`unsigned` changes an instruction account's `isSigner` flag to false. It does not forge a PDA signature or demonstrate breaking cryptography. The resulting transactions test the target program's response to missing authorization.
14
15The independent measurement consumer, [tools/demo/measure_attempts.py](../tools/demo/measure_attempts.py), refetches reported signatures from RPC, extracts their actual reasons, and enumerates the successful transactions recorded with the attacker wallet as fee payer. Its original fetch commitment is `confirmed`. Its input signatures come from the operator's report; it is not a search over every possible attack or all wallet history.
16
17For this review, all 33 listed signatures were fetched again from public devnet RPC using `getTransaction`, `encoding: jsonParsed`, and **finalized** commitment. The complete responses are cached in [stages-probe-ledger.json](demo/data/stages-probe-ledger.json), including the verification timestamp, accounts, instructions, logs, fees and pre/post balances. All 33 signatures and extracted reasons match the measured dataset, all have non-null transaction errors, and all have unchanged pre/post token-balance arrays. They paid 200,000 lamports in aggregate fees. The response cache is an inspection aid; it can be checked against RPC or Explorer using the listed signatures.
18
19Failure reverts instruction state changes, while transaction fees remain charged. These semantics are documented by Solana in [Transactions](https://solana.com/docs/core/transactions) and [Fees](https://solana.com/docs/core/fees). Therefore unchanged token balances in a failed transaction are expected atomicity evidence, not independent proof that every underlying account constraint is correct.
20
21## Which tests are useful, and for what
22
23The strongest bond-specific cases exercise validly authorized actions with invalid business consequences: sending to an unregistered holder, bypassing the one-ATA model, forging a position update outside an actual transfer, releasing an underfunded event, redirecting a beneficiary, paying twice, claiming with no record-time entitlement, exceeding an offer cap, transferring tender-locked bonds, substituting a different event's vault, and mixing interest/principal event types.
24
25The raw mint, transfer, vault-drain and loader-authority probes are useful authority regression tests. Their rejection is largely supplied by Solana's native/token programs. They do not add novel bond mathematics or establish that a genuinely authorized administrator cannot misuse its powers. Clearing a PDA's signer flag tests missing authorization, not hostile execution of an authorized CPI.
26
27Several tests deliberately use cooperation from privileged or rightful actors. `send-unregistered`, `second-account`, `skip-hook`, `sell-tendered`, and `trade-at-maturity` use a holder's real signature. `fee-cash-token` uses the registrar to configure an unsuitable cash mint. `place-late` uses the issuance authority. `frozen-cash` uses the bank's actual cash freeze authority to create a failure, followed by thawing and payment. Those are meaningful policy and recovery tests, with those permissions made explicit in the cards.
28
29The burn probes show rejection of ordinary burn on this permissioned-burn configuration and rejection of incorrect/missing permissioned-burn authority. They do not contain an otherwise-valid ordinary burn signed by the rightful owner. A failure may establish an early token/configuration check without exercising every later bond rule.
30
31The hostile dataset also records 11 successful attacker-paid transactions, four of which send cash to legitimate holder accounts. Opening an event, confirming its full funding and paying its predetermined beneficiaries are intentionally permissionless producer actions. The measured successful transactions give zero positive cash or bond deltas to the attacker. “Attacker can submit a payment” is consequently an intended servicing capability, not a payout-redirection exploit.
32
33These observations cover this profile and these recorded runs. They do not establish exhaustive attack coverage, arbitrary instruction composition, concurrency under adversarial scheduling, malicious upgrades signed by the genuine upgrade authority, availability of the external cash asset, or million-holder throughput. A 1,000-holder functional run measures its own outcomes, not the capacity of a million-holder market.
34
35## Two distinctions made explicit in the demo
36
371. The crowd dataset's “trades” move bond tokens and update positions, with zero cash trade-leg movements. They demonstrate atomic securities transfer and register updating. They do not demonstrate delivery versus payment between a buyer and seller. The trade heading, caption and evidence cards now state the securities-leg scope.
382. [tamper-probe-local.json](demo/data/tamper-probe-local.json) is a separate **localnet** run. A holder sends an unsolicited 0.000001 cash deposit into a vault; two of 23 reconciliation checks flag the mismatch against expected funding. No theft occurred. An external token transfer into a vault can be valid while violating the scenario's expected funding history. The demo now names the network and describes discrepancy detection. It supplies the local signature and vault in the card without inventing a public devnet Explorer URL.
39
40The 3,959 crowd-run checks are recorded assertions in an independent scenario audit. Audit squares now name the exact assertion; holder assertions also expose the corresponding quantities, expected/measured coupons, wallet and payment transactions. They are not 3,959 independent attack discoveries.
41
42## What changed locally, and why
43
44| Component | Change | Purpose |
45|---|---|---|
46| `tools/demo/stages_audit.py` | Added a public evidence registry, per-probe mechanisms/limits, finalized-record consistency checks, source snapshots and a readable probe-review page | Give each demo claim a traceable producer and measured consumer, and distinguish current code from historical execution |
47| `tools/demo/build_stages.py` | Added native reference anchors to metrics, rules, every displayed refusal and each stage; embedded the evidence registry and chart bindings | Make inspection a single click and preserve evidence links without JavaScript |
48| `tools/demo/stages_template.html` | Added an evidence card after one second of hover; immediate keyboard-focus preview; direct clickable chart marks; close/Escape handling; matching light/dark styling | Let auditors inspect signatures, reasons, actors, amounts and supporting links without losing their place |
49| `docs/demo/data/stages-probe-ledger.json` | Cached all 33 finalized JSON-RPC transaction responses with endpoint and verification time | Allow inspection of actual errors, logs, signer accounts and balances rather than relying only on captions |
50| `docs/demo/audit/evidence.json` | Generated public registry with probe rows, audit assertions, record grids, holder addresses and source hashes | Supply machine-readable evidence and chart-to-evidence mappings |
51| `docs/demo/audit/review.html` | Generated static explanation and all 33 probe mechanisms, limits, errors, transaction links and instruction constructors | Make the meaning of “attacks” inspectable even without the hover UI |
52| `docs/demo/audit/source/` | Generated escaped, numbered HTML snapshots of explicitly selected public source files, each with SHA-256 and Git baseline | Make actual code and scenario lines available from the static demo without depending on an absent public repository remote |
53| `docs/demo/stages.html` | Rebuilt from the template and existing measurements | Keep the checked-in demonstration consistent with its source |
54| `tools/demo/check_stages.cjs` | Added reproducible browser checks against a temporary loopback server | Verify actual hover, navigation, keyboard, mobile, dark and no-JavaScript behavior |
55| This document | Recorded findings, changes, reasons and validation | Make the review itself inspectable |
56
57Trade dots have individual transaction bindings. Coupon squares have individual holder bindings to their batch payment, record quantity, expected cash and measured cash. Offer bars distinguish net tender elections from scenario inputs versus actual accepted retirement movements in the ledger. Underfunded-vault bars link to the short-funding refusal; successful funding references belong to the crowd run. Each audit square maps to its specific recorded assertion. Textbook figures link to their cited rule documents. Decorative or aggregate chart marks use their stage-level evidence rather than claiming a fictitious individual transaction.
58
59Preview contents are cached and embedded: hover sends no RPC, Explorer or iframe request. Clicking immediately follows an ordinary anchor, including on touch devices. Moving into the popup preserves it long enough to inspect and click its links. Cards use the page's existing fonts and color variables, constrain their size to the viewport, and allow their own scrolling. Arrow/Page navigation does not intercept controls inside the popup. Source HTML escapes all code, and inline evidence JSON escapes HTML delimiters.
60
61Keyboard focus opens a card immediately; Tab enters its controls. Escape or closing the card returns focus to the original evidence link. Transaction/source/data links appear above the long details, so a long signature does not hide the inspection actions. The cached page embeds only referenced evidence and shares repeated reference objects, reducing the initial implementation's approximately 9 MB HTML to approximately 3.8 MB. The full evidence registry remains a separate linked JSON artifact. This is a functional evidence viewer, not a throughput benchmark.
62
63Only explicitly selected public source files and measured datasets are exported. Private key files and operator reports are not copied. A source snapshot's Git revision identifies the build's base commit; its hash identifies the actual local file content, which can contain uncommitted changes. Source snapshots are **not** an attestation that a historical devnet transaction executed a binary compiled from these exact current files.
64
65The builder now requires the finalized probe ledger and rejects signature/reason disagreements before generating new evidence. It does not fetch the network during a page build. The existing measurement scripts and on-chain program were left untouched.
66
67## Validation
68
69Completed:
70
71- Read-only finalized RPC verification of all 33 listed probes, matching stored signatures, reasons and guard tokens; unchanged token-balance arrays; actual signer, fee-payer and fee extraction.
72- Successful rebuild of all nine stages from the unchanged scenario measurements, with finalized probe-record consistency checks.
73- All generated local reference targets and source-line fragments resolve. Source snapshot hashes match their selected current repository files.
74- Headless Chromium: all chart bindings resolve; 600 trade dots, 1,000 payment squares and 3,959 audit squares match their inputs. Hover stays closed at 750 ms and opens after one second; brief hover cancels; moving into the card keeps it open. No evidence/RPC/Explorer request is made on hover. The existing Google Fonts stylesheet may lazily load a font weight/glyph when a card first appears.
75- Keyboard focus, Tab into the card, close/Escape and focus restoration work; PageDown in the card does not navigate the stages. Clicking a refusal opens its exact transaction URL immediately. Payment and audit cards show the expected record/amount/check fields.
76- Desktop at 1,440 pixels and mobile at 390 pixels, including dark mode: cards remain within the viewport and the page has no horizontal overflow. Matching chart colors were preserved by having SVG links inherit the existing color.
77- JavaScript-disabled page: all nine static stages and metric/refusal references remain available. Static probe review: all 33 refusal rows and 11 permitted-servicing rows have direct transaction links. No browser JavaScript errors in the normal interactive page.
78- Existing D3 7.9.0 was cached for browser checks and served at its original CDN URL with its existing integrity attribute. Explorer navigation was intercepted after testing the destination URL; the external Explorer UI itself was not asserted. Code/source pages and datasets were served from the generated local tree. Browser screenshots were written to `/tmp/codex-stages-auditor-desktop.png` and `/tmp/codex-stages-auditor-mobile.png`.
79- The Kazakhstan CSD reference returned HTTP 200 with PDF content type; the AFME 2012 document redirects to its PDF and returned HTTP 200. ECB SCoRE and T2S documents resolve through the web reader. These checks validate access to the existing cited sources, not a fresh legal applicability review.
80- `git diff --check` passed. No deployment, key-file export, on-chain write, or change to the program/attack producer was performed.
81
82Build command:
83
84```sh
85.venv/bin/python3 tools/demo/build_stages.py \
86  docs/demo/data/devnet-crowd-1000.json \
87  docs/demo/data/devnet-keeper.json \
88  docs/demo/data/tamper-probe-local.json \
89  docs/demo/data/devnet-hostile-attempts.json \
90  docs/demo/stages.html
91```
92
93Browser check command, with Playwright installed/resolvable and an installed Chromium:
94
95```sh
96node tools/demo/check_stages.cjs
97```
98
99For this workspace's cached installation, the check used `NODE_PATH=/home/caiborg/.npm/_npx/705bc6b22212b352/node_modules`, `STAGES_CHROMIUM=/home/caiborg/.cache/ms-playwright/chromium-1223/chrome-linux64/chrome`, and `STAGES_D3_PATH=/tmp/codex-stages-d3.min.js`. The loopback server closes when the check finishes.
100
101The final generated probe table lives in [audit/review.html](demo/audit/review.html). It is produced from the same per-probe assessment used in the hover cards, so the displayed explanations and the review stay consistent.