Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -601,10 +601,10 @@ Everything below runs offline, with no deployed contracts, except three fork sui
| Suite | Count | Command |
|---|---|---|
| Contracts: unit, fuzz, E2E, upgrade, deploy-script, handover and 22 invariants | 799 | `forge test` |
| Oracle | 1514 | `cd oracle && node --test` |
| Oracle | 1532 | `cd oracle && node --test` |
| SDK | 385 | `cd packages/sdk && npx vitest run` |

Counts are individual tests, so each of the 22 invariants counts once. The contracts were counted on 15 November 2026, the SDK on 15 November and the oracle on 14 November. Without a fork URL, 787 of the contract tests run and 12 skip. Run after `npm run build`, 376 of the SDK's 385 pass and 9 skip: the 8 integration tests, which need a live deployment, and one check that runs only in CI. Without a build, the 9 built-package tests skip too. Vitest strips types without checking them, so `npm run typecheck` in `packages/sdk` checks the tests against the SDK's types as well as the sources. [`scripts/mutation`](scripts/mutation/README.md) holds the harnesses that measure whether these tests would catch a deliberate break in the contracts or deploy scripts.
Counts are individual tests, so each of the 22 invariants counts once. The contracts were counted on 15 November 2026, the SDK on 15 November and the oracle on 15 November. Without a fork URL, 787 of the contract tests run and 12 skip. Run after `npm run build`, 376 of the SDK's 385 pass and 9 skip: the 8 integration tests, which need a live deployment, and one check that runs only in CI. Without a build, the 9 built-package tests skip too. Vitest strips types without checking them, so `npm run typecheck` in `packages/sdk` checks the tests against the SDK's types as well as the sources. [`scripts/mutation`](scripts/mutation/README.md) holds the harnesses that measure whether these tests would catch a deliberate break in the contracts or deploy scripts.

Merges to `main` carry `[skip ci]`, to save CI minutes, so the push to `main` does not run the suites again. A change to code runs them on its pull request and merges only once every job there has passed; a docs-only change is checked locally with `node scripts/check-docs.mjs`. Each is checked against the `main` its branch started from, so two changes merged close together can still break `main`. That happened once, on 11 November 2026, and the next merge fixed it. The rule that every job must pass dates from 14 November 2026: before it, #281, #282 and #288 merged with their oracle job failing, and #283 and #297 fixed the tests that failed. On 13 November the oracle and SDK suites were run on `main` at `eaccb91` and passed.

Expand Down
2 changes: 1 addition & 1 deletion docs/whitepaper.md
Original file line number Diff line number Diff line change
Expand Up @@ -635,7 +635,7 @@ apply to a fresh deployment, not to the testnet.

**Test coverage**, as of 15 November 2026: 799 contract tests across 36 Foundry test files
including fuzz and invariant tests (the two slash drill suites fork Arc testnet themselves, and
the twelve in `SplitAuthorityFork` skip without `--fork-url`), 1514 oracle tests and 385 in the SDK (9 skip
the twelve in `SplitAuthorityFork` skip without `--fork-url`), 1532 oracle tests and 385 in the SDK (9 skip
outside CI and without a live deployment; every test that runs passes). CI runs Foundry, the oracle and
SDK suites, and Slither static analysis on every push, plus a documentation check that
fails when the site states something the contracts do not.
Expand Down
10 changes: 10 additions & 0 deletions oracle/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -131,6 +131,10 @@ answers 202 with `"durable": false` instead of 200 while a save is failing, and
those as `accepted_not_durable`. Pulled payments are found again by the next scan;
attested outcomes are on chain nowhere, so those do not come back.

A save writes the whole state and fsyncs it, about 2.8 s at the ledger's caps, so `/attest` writes that arrive
within 100 ms of each other share one, and each is answered after a save that holds it.
`sigvara_oracle_state_saves_total` counts saves.

`/flag`, `/flag/resolve` and `/link` say the same thing for the same reason: 202 with
`"durable": false` while a save is failing, counted in
`sigvara_oracle_writes_not_durable_total`. The change is held in memory and written by the
Expand Down Expand Up @@ -472,6 +476,12 @@ evidence nobody can fetch is evidence nobody can audit.
The response names `committedFields` — the exact fields the root commits to, in leaf
order — so a verifier need not read this source to know what is covered.

The whole list comes in one body: about 32 MB for an agent at the cap of 25,000 payments, 41 MB with
payer outcomes published. `?offset=N&limit=M`, with M at most 1,000, serves part of it: the same fields,
then `offset`, `next` (where the next part starts, or null at the end) and those payments with their
proofs. A body is built a slice at a time, so other requests are answered while it is, and kept until the
agent's payments change. An agent with no payments is not kept.

Payments are served in the order the root is built over: by settlement time, then transaction and
payer, with a payment chain's after the scored chain's. Two operators credit the same payments in
different orders, and the order of the leaves can change the root, so the order they were credited in
Expand Down
36 changes: 36 additions & 0 deletions oracle/attest.test.js
Original file line number Diff line number Diff line change
Expand Up @@ -228,6 +228,42 @@ test('a refused replay does not lock the payer out of the agent', async () => {
assert.equal(next.status, 200, next.text);
});

// A save writes and fsyncs the whole state, about 2.8 s at the ledger's caps, and every accepted /attest had its own.
test('attestations that arrive together share a save, and each is answered after it', async () => {
const saves = async () => Number((await oracle.call('GET', '/metrics')).text.match(/^sigvara_oracle_state_saves_total (\d+)$/m)[1]);
const posts = Array.from({ length: 5 }, () => {
const agent = world.addAgent();
return [agent.didHash, world.addTx([{ from: wallet(), to: agent.agentAddress, value: 5n * USDC }])];
});
const before = await saves();

const answers = await Promise.all(posts.map(([didHash, tx]) => attest(didHash, tx, { success: true, token: AUDITOR })));

for (const r of answers) assert.equal(r.status, 200, r.text);
const used = (await saves()) - before;
assert.ok(used >= 1 && used <= 2, `${used} saves for 5 attestations`);
});

// Anyone can copy a credited settlement from /evidence, and each replay used to cost six chain reads before its 409.
test('a replayed settlement is refused before the chain is read, and an auditor can still give it an outcome', async () => {
const agent = world.addAgent();
const tx = world.addTx([{ from: wallet(), to: agent.agentAddress, value: 5n * USDC }]);
assert.equal((await attest(agent.didHash, tx, { success: true })).status, 200);
const receiptReads = () => oracle.calls().filter((c) => c.name === 'receipt' && c.args[0] === tx.toLowerCase()).length;
const before = receiptReads();

const replay = await attest(agent.didHash, tx.toUpperCase().replace('0X', '0x'), { success: true });
assert.equal(replay.status, 409, replay.text);
assert.equal(replay.body.code, 'replayed');
assert.equal(receiptReads(), before, 'refused without reading the payment');

// An outcome is something to add, so the auditor's report goes through the full check and is recorded.
const audited = await attest(agent.didHash, tx, { success: false, token: AUDITOR });
assert.equal(audited.status, 200, audited.text);
assert.equal(audited.body.outcomeRecorded, true);
assert.equal(receiptReads(), before + 1);
});

test('a stranger is held to the cooldown, and the refusal does not burn the receipt', async () => {
const agent = world.addAgent();
const payer = wallet();
Expand Down
56 changes: 43 additions & 13 deletions oracle/bond-watch.js
Original file line number Diff line number Diff line change
Expand Up @@ -7,26 +7,54 @@
// One is let back, and read at the next epoch like any other agent, when a log says its bond may have changed: a stake
// deposited, a withdrawal, a slash or a status change naming it, and every one when the minimum stake changes. The logs
// are read from where the last epoch's stopped, a little before it in case the node that answered the reads was behind
// the one that gave the head. Every agent is read on the first epoch, once a day after that, and whenever the logs or
// the head cannot be read, so a change no log showed waits a day at most. In memory only: a restart reads every agent.
// the one that gave the head. Every agent is read on the first epoch and whenever the logs or the head cannot be read.
// After that each one is read again within a day of the epoch that found it unbonded, so a change no log showed waits a
// day at most. In memory only: a restart reads every agent.
//
// Those reads are spread over the day's epochs, a share each, the agents found longest ago first. They used to come all
// at once: every agent read in one epoch, about 0.47 s each, which at 10,000 registrations (about 50 USDC of gas on Arc
// mainnet) is 78 minutes (performance review, 15 November).
//
// No dependencies, so it can be tested on its own.

const SWEEP_MS = 24 * 3_600_000;
const OVERLAP_BLOCKS = 100;

function createBondWatch({ sweepMs = SWEEP_MS, overlapBlocks = OVERLAP_BLOCKS } = {}) {
const unbonded = new Set();
// The head the logs were last read up to, and when every agent was last read.
// Each agent left out, with the time of the epoch that found it unbonded, the earliest first.
const unbonded = new Map();
// The head the logs were last read up to.
let cursor = null;
let sweptAtMs = null;
// When the last epoch began, and how many agents are owed a read so far: the unbonded share of the time since,
// carried over in fractions, so a few agents are not read every epoch for being rounded up.
let refreshedAtMs = null;
let owed = 0;
const key = (didHash) => String(didHash).toLowerCase();

function letEveryoneBack() {
unbonded.clear();
owed = 0;
}

// The share of the agents left out that the time since the last epoch is owed, and any found a day ago or more.
function letDueBack(nowMs, elapsedMs) {
owed += (unbonded.size * Math.max(0, elapsedMs)) / sweepMs;
for (const [didHash, foundAtMs] of unbonded) {
if (owed >= 1) owed -= 1;
else if (nowMs - foundAtMs < sweepMs) break;
unbonded.delete(didHash);
}
if (unbonded.size === 0) owed = 0;
}

return {
/** Whether the epoch leaves this agent out of its reads. */
excluded: (didHash) => unbonded.has(key(didHash)),
/** An agent an epoch's read found below the minimum stake. */
add(didHash) { unbonded.add(key(didHash)); },
/** An agent an epoch's read found below the minimum stake, dated by that epoch. */
add(didHash) {
unbonded.delete(key(didHash));
unbonded.set(key(didHash), refreshedAtMs ?? 0);
},
size: () => unbonded.size,

/**
Expand All @@ -35,33 +63,35 @@ function createBondWatch({ sweepMs = SWEEP_MS, overlapBlocks = OVERLAP_BLOCKS }
* epoch, with `error` when that is because a read failed.
*/
async refresh({ readHead, readChanges, nowMs }) {
const elapsedMs = refreshedAtMs === null ? 0 : nowMs - refreshedAtMs;
refreshedAtMs = nowMs;
let head;
try {
head = await readHead();
} catch (error) {
unbonded.clear();
letEveryoneBack();
cursor = null;
return { full: true, error };
}
if (cursor === null || nowMs - sweptAtMs >= sweepMs) {
unbonded.clear();
if (cursor === null) {
letEveryoneBack();
cursor = head;
sweptAtMs = nowMs;
return { full: true };
}
letDueBack(nowMs, elapsedMs);
const from = Math.max(0, cursor - overlapBlocks + 1);
cursor = Math.max(cursor, head);
if (head < from) return { full: false };
try {
const changes = await readChanges(from, head);
if (changes.minimumChanged) {
unbonded.clear();
letEveryoneBack();
return { full: true };
}
for (const didHash of changes.agents) unbonded.delete(key(didHash));
return { full: false };
} catch (error) {
unbonded.clear();
letEveryoneBack();
return { full: true, error };
}
},
Expand Down
5 changes: 3 additions & 2 deletions oracle/chain.js
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,8 @@ const STAKE_VIEW_ABI = ['function hasMinimumStake(bytes32 didHash) view returns

const { SCORE_FACTORS } = require('./epoch-policy');
const { readSplitting, spanRefused } = require('./log-spans');
const { isTransientReadError, readWithBackoff, MAX_BATCH_CALLS } = require('./read-retry');
const { isTransientReadError, readWithBackoff } = require('./read-retry');
const { rpcProvider } = require('./rpc-provider');
const reviewers = require('./reviewers');
const { createFunderReader } = require('./funder-scan');

Expand Down Expand Up @@ -182,7 +183,7 @@ function init(cfg, deps = {}) {
cfg_ = cfg;
txWaitMs = cfg.txWaitMs ?? DEFAULT_TX_WAIT_MS;
txPollMs = cfg.txPollMs ?? DEFAULT_TX_POLL_MS;
provider = deps.provider ?? new ethers.JsonRpcProvider(cfg.rpcUrl, undefined, { batchMaxCount: MAX_BATCH_CALLS });
provider = deps.provider ?? rpcProvider(cfg.rpcUrl, cfg.expectedChainId);
wallet = deps.wallet ?? new CappedWallet(cfg.privateKey, provider, capsFromConfig(cfg));
identityContract = deps.identityContract ?? new ethers.Contract(cfg.identityAddress, IDENTITY_ABI, provider);
reputationContract = deps.reputationContract ?? new ethers.Contract(cfg.reputationAddress, REPUTATION_ABI, wallet);
Expand Down
12 changes: 6 additions & 6 deletions oracle/credit-reread.test.js
Original file line number Diff line number Diff line change
Expand Up @@ -121,7 +121,7 @@ const ev = (i, ts, over = {}) => Object.freeze({
const endsAt = (e) => (e.removedAt != null ? Number(e.removedAt) : Infinity);
const NO_CHAIN = paymentChains.readConfig({}, { scoredChainId: 5042002 });

test('a root made before a removal still reproduces from the state that holds it, and the next one leaves it out', () => {
test('a root made before a removal still reproduces from the state that holds it, and the next one leaves it out', async () => {
const a = ev(1, NOW - 60 * MIN);
const b = ev(2, NOW - 50 * MIN);
const before = rootFor([a, b]); // proposed at NOW - 30 min
Expand All @@ -133,16 +133,16 @@ test('a root made before a removal still reproduces from the state that holds it
assert.equal(rootFor(paymentChains.eventsAt(held, NOW, NO_CHAIN)), rootFor([a]));

// The checker auditing each proposal from the same state reaches the same answer.
const audit = (atMs, root, cuts) => evidenceAsOf(
const audit = async (atMs, root, cuts) => evidenceAsOf(
paymentChains.eventsAt(held, atMs, NO_CHAIN, undefined, { keepRemoved: true }), atMs, root, { endsAt, ...(cuts ? { cuts } : {}) },
);
assert.equal(audit(NOW - 30 * MIN, before).matchedRoot, true, 'the earlier proposal');
assert.equal(audit(NOW, rootFor([a])).matchedRoot, true, 'the later one');
assert.equal(audit(NOW, before).matchedRoot, false, 'a proposal after the removal that still counts it is a disagreement');
assert.equal((await audit(NOW - 30 * MIN, before)).matchedRoot, true, 'the earlier proposal');
assert.equal((await audit(NOW, rootFor([a]))).matchedRoot, true, 'the later one');
assert.equal((await audit(NOW, before)).matchedRoot, false, 'a proposal after the removal that still counts it is a disagreement');

// With payment chains on, a proposal dated after the removal whose evidence was cut before it still counted it.
const cuts = [NOW - 19 * MIN, NOW - 20 * MIN, NOW - 21 * MIN];
assert.equal(audit(NOW - 18 * MIN, before, cuts).matchedRoot, true);
assert.equal((await audit(NOW - 18 * MIN, before, cuts)).matchedRoot, true);
});

test('the scan canary never points at a payment a reorganization removed', () => {
Expand Down
27 changes: 22 additions & 5 deletions oracle/evidence-as-of.js
Original file line number Diff line number Diff line change
Expand Up @@ -41,22 +41,39 @@ const merkle = require('./merkle');
*
* Only the fixed order is read (payment-chains.eventsAt): it is the order every proposal commits to.
*
* Every tree tried shares one memo of pair hashes (merkle.pairOf). Neighbouring cut-offs hold nearly the same payments
* in the same order, so their trees share every pair left of where they differ, and each was built whole: a miss at
* the cap of 25,000 payments held the event loop for 22 s (performance review, 15 November). A cut-off that counts
* the same payments as the one before is skipped, and other work runs between trees.
*
* @param {object[]} events one agent's payment events, in the fixed order
* @param {number} atMs the proposal's time, in ms
* @param {string|null} committedRoot the proposal's evidenceRoot, or null when it has none
* @param {{ eligibleAt?: (e: object) => number, endsAt?: (e: object) => number, cuts?: number[] }} [options]
* @returns {{ events: object[], matchedRoot: boolean }}
* @returns {Promise<{ events: object[], matchedRoot: boolean }>}
*/
function evidenceAsOf(events, atMs, committedRoot, { eligibleAt = (e) => Number(e.ts), endsAt = () => Infinity, cuts = [] } = {}) {
async function evidenceAsOf(events, atMs, committedRoot, { eligibleAt = (e) => Number(e.ts), endsAt = () => Infinity, cuts = [] } = {}) {
if (!Number.isFinite(atMs)) throw new TypeError('evidenceAsOf: atMs (ms) is required');
const countedBy = (list, cut) => list.filter((e) => eligibleAt(e) <= cut && endsAt(e) > cut);
const committed = typeof committedRoot === 'string' ? committedRoot.toLowerCase() : null;
if (committed) {
const pairs = new Map();
// One unset copy of each event, so its leaf is hashed once however many cut-offs hold it.
const unsetCopies = new Map();
const unsetOf = (e) => {
if (!signedAfter(e, atMs)) return e;
if (!unsetCopies.has(e)) unsetCopies.set(e, withoutPayerOutcome(e));
return unsetCopies.get(e);
};
let last = null;
for (const cut of [atMs, ...cuts.filter((c) => c < atMs)]) {
const set = countedBy(events, cut);
if (merkle.rootFor(set).toLowerCase() === committed) return { events: set, matchedRoot: true };
const unset = set.map((e) => (signedAfter(e, atMs) ? withoutPayerOutcome(e) : e));
if (unset.some((e, i) => e !== set[i]) && merkle.rootFor(unset).toLowerCase() === committed) {
if (last && set.length === last.length && set.every((e, i) => e === last[i])) continue;
if (last) await new Promise((resolve) => setImmediate(resolve));
last = set;
if (merkle.rootFor(set, pairs).toLowerCase() === committed) return { events: set, matchedRoot: true };
const unset = set.map(unsetOf);
if (unset.some((e, i) => e !== set[i]) && merkle.rootFor(unset, pairs).toLowerCase() === committed) {
return { events: unset, matchedRoot: true };
}
}
Expand Down
Loading
Loading