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
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -601,7 +601,7 @@ 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 | 1532 | `cd oracle && node --test` |
| Oracle | 1542 | `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 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.
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`), 1532 oracle tests and 385 in the SDK (9 skip
the twelve in `SplitAuthorityFork` skip without `--fork-url`), 1542 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: 8 additions & 2 deletions oracle/chain.js
Original file line number Diff line number Diff line change
Expand Up @@ -1061,9 +1061,15 @@ async function getChallengeWindow() {
// would trigger premature finalize attempts that just revert and waste gas).
// Retried like every other read: an epoch reads this before anything else, so one throttled
// answer used to cost the whole epoch.
async function getLatestBlockTimestamp() {
// The latest block's time and when it was read. A caller that can use a reading a few seconds old passes `maxAgeMs`:
// an epoch's per-agent steps and the read routes each asked the chain one round trip at a time.
let latestBlockTime = null;

async function getLatestBlockTimestamp({ maxAgeMs = 0 } = {}) {
if (maxAgeMs > 0 && latestBlockTime && Date.now() - latestBlockTime.atMs <= maxAgeMs) return latestBlockTime.seconds;
const block = await readWithBackoff('latest block', () => provider.getBlock('latest'));
return Number(block.timestamp);
latestBlockTime = { seconds: Number(block.timestamp), atMs: Date.now() };
return latestBlockTime.seconds;
}

// ---- Epoch-fee gating (opt-in) --------------------------------------------
Expand Down
15 changes: 15 additions & 0 deletions oracle/chain.test.js
Original file line number Diff line number Diff line change
Expand Up @@ -999,3 +999,18 @@ test('isRateLimited and isSlotTaken do not overlap', () => {
assert.equal(chain.isSlotTaken(taken), true);
assert.equal(chain.isRateLimited(taken), false);
});

// An epoch's per-agent steps, /score and /evidence each read the chain's clock one round trip at a time.
test('getLatestBlockTimestamp reuses a reading up to maxAgeMs old, and reads afresh without one', async () => {
let reads = 0;
chain.init(CFG, {
provider: { getBlock: async (tag) => { assert.equal(tag, 'latest'); reads += 1; return { timestamp: 1000 + reads }; } },
identityContract: makeFakeIdentityContract({ events: [] }),
reputationContract: makeFakeReputationContract(),
});
assert.equal(await chain.getLatestBlockTimestamp(), 1001);
assert.equal(await chain.getLatestBlockTimestamp({ maxAgeMs: 5_000 }), 1001, 'a reading under 5 s old is reused');
assert.equal(reads, 1);
assert.equal(await chain.getLatestBlockTimestamp(), 1002, 'without maxAgeMs the chain is read');
assert.equal(reads, 2);
});
10 changes: 8 additions & 2 deletions oracle/external.js
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,8 @@ let chainIdError = null;
// The check in flight, which every caller shares, and when the last one finished (ms).
let checking = null;
let checkedAt = 0;
// How long a feed that could not be reached is left before a caller that accepts a cached answer asks again.
const UNREACHABLE_RECHECK_MS = 30_000;


// deps lets tests inject fake contracts. Production (index.js) calls init(cfg).
Expand All @@ -127,9 +129,10 @@ function init(cfg, deps = {}) {
idContract = deps.idContract ?? new ethers.Contract(cfg.externalIdentity, ID_ABI, provider);
repContract = deps.repContract ?? new ethers.Contract(cfg.externalReputation, REP_ABI, provider);
// A re-init points at a different chain, so anything cached about the old one is a
// lie until proven otherwise.
// lie until proven otherwise, and the new one is asked at once.
chainId = null;
chainIdError = null;
checkedAt = 0;
}

/**
Expand All @@ -142,10 +145,13 @@ function init(cfg, deps = {}) {
* A caller arriving while a check is in flight waits for it rather than reading the cache.
* A cached id younger than `maxAgeMs` is returned without asking; the default asks every
* time. An id that cannot be read again is dropped, so a failed re-check reads as unreachable.
* A feed that could not be reached is asked again after at most UNREACHABLE_RECHECK_MS for a
* caller that accepts a cached answer: /health asked a down feed on every request.
*/
async function refreshChainId(maxAgeMs = 0, nowMs = Date.now()) {
if (!enabled) return chainId;
if (!checking && (chainId === null || nowMs - checkedAt >= maxAgeMs)) {
const ageLimit = chainId === null ? Math.min(maxAgeMs, UNREACHABLE_RECHECK_MS) : maxAgeMs;
if (!checking && nowMs - checkedAt >= ageLimit) {
checking = checkChainId().finally(() => { checkedAt = Date.now(); checking = null; });
}
return checking ?? chainId;
Expand Down
19 changes: 19 additions & 0 deletions oracle/external.test.js
Original file line number Diff line number Diff line change
Expand Up @@ -575,3 +575,22 @@ test('readLinkLogs: filters on the key, and returns each log\'s agent, value and
assert.deepEqual(calls, [['queryFilter', 'sigvara', 100, 199]]);
external.init({ externalRpc: '', externalIdentity: '', externalReputation: '' });
});

// /health asked a feed it could not reach on every request, each ask up to READ_TIMEOUT_MS.
test('refreshChainId: an unreachable feed is asked again after 30 s for a caller that takes a cached answer, at once for one that does not', async () => {
let calls = 0;
external.init(CFG, {
provider: { send: async () => { calls += 1; throw new Error('ECONNREFUSED'); } },
idContract: {}, repContract: {},
});
const FIVE_MIN = 5 * 60_000;
const t = Date.now();
assert.strictEqual(await external.refreshChainId(FIVE_MIN, t), null);
assert.strictEqual(calls, 1);
assert.strictEqual(await external.refreshChainId(FIVE_MIN, t + 10_000), null);
assert.strictEqual(calls, 1, 'not asked again within 30 s');
assert.strictEqual(await external.refreshChainId(FIVE_MIN, t + 31_000), null);
assert.strictEqual(calls, 2, 'asked again after 30 s');
assert.strictEqual(await external.refreshChainId(0, t + 31_001), null);
assert.strictEqual(calls, 3, 'a caller that takes no cached answer is always asked for');
});
12 changes: 11 additions & 1 deletion oracle/http-helpers.js
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,15 @@ function bodyErrorStatus(err) {
return 400;
}

// What a route answers for an error its own checks did not catch, and what it logs. A body readBody could not take is
// said as it is. Anything else is answered `bad request`, and its words go only to the log: they can name what a
// caller should not see, such as a failing node's URL.
const READ_ERRORS = new Set(['body_too_large', 'body_timeout', 'bad_json']);
function uncaughtReply(err) {
if (err && READ_ERRORS.has(err.code)) return { status: bodyErrorStatus(err), body: { error: err.message }, log: null };
return { status: 400, body: { error: 'bad request' }, log: String((err && err.message) || err) };
}

// req only needs to be an EventEmitter emitting 'data' | 'end' | 'error' and
// exposing destroy() — a real http.IncomingMessage satisfies this, and so
// does a plain fake in tests. A declared content-length is read from
Expand Down Expand Up @@ -79,7 +88,7 @@ async function readBody(req, maxBodySize = MAX_BODY_SIZE, deadlineMs = BODY_DEAD
req.on('end', () => {
clearTimeout(deadline);
try { resolve(JSON.parse(Buffer.concat(chunks).toString() || '{}')); }
catch { reject(new Error('Invalid JSON')); }
catch { reject(Object.assign(new Error('Invalid JSON'), { code: 'bad_json' })); }
});
req.on('error', (err) => {
clearTimeout(deadline);
Expand Down Expand Up @@ -461,6 +470,7 @@ module.exports = {
json,
readBody,
bodyErrorStatus,
uncaughtReply,
readCredentials,
identifyCaller,
mayAttestUnauthenticated,
Expand Down
24 changes: 24 additions & 0 deletions oracle/http-helpers.test.js
Original file line number Diff line number Diff line change
Expand Up @@ -655,3 +655,27 @@ test('weakCredentials: names the credentials shorter than 32 characters, never t
const weak = weakCredentials(new Map([['admin', 'x'.repeat(31)], ['ok', 'y'.repeat(32)], ['tiny', 'z']]));
assert.deepEqual(weak, ['admin', 'tiny']);
});

// /attest and the token routes answered an error none of their checks expected with its raw message, which can name
// what a caller should not see.
test('uncaughtReply: a body that could not be read is said as it is; anything else is a bad request, its words kept for the log', () => {
const { uncaughtReply } = require('./http-helpers');
const tooBig = Object.assign(new Error('Request body too large'), { code: 'body_too_large' });
assert.deepEqual(uncaughtReply(tooBig), { status: 413, body: { error: 'Request body too large' }, log: null });
const badJson = Object.assign(new Error('Invalid JSON'), { code: 'bad_json' });
assert.deepEqual(uncaughtReply(badJson), { status: 400, body: { error: 'Invalid JSON' }, log: null });
const leak = new Error('request to https://rpc.example.invalid/v2/very-secret-key failed');
assert.deepEqual(uncaughtReply(leak), { status: 400, body: { error: 'bad request' }, log: leak.message });
});

test('readBody: invalid JSON is refused as a body error, with its own words', async () => {
const { readBody, uncaughtReply } = require('./http-helpers');
const { EventEmitter } = require('node:events');
const req = Object.assign(new EventEmitter(), { headers: {}, destroy() {} });
const reading = readBody(req);
req.emit('data', Buffer.from('{'));
req.emit('end');
const err = await reading.catch((e) => e);
assert.equal(err.code, 'bad_json');
assert.deepEqual(uncaughtReply(err).body, { error: 'Invalid JSON' });
});
31 changes: 21 additions & 10 deletions oracle/index.js
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ const {
const { createBondWatch } = require('./bond-watch');
const { numberSetting } = require('./config');
const {
json, readBody, bodyErrorStatus, readCredentials, identifyCaller, mayAttestUnauthenticated, parseScorePath, parseDidHash,
json, readBody, uncaughtReply, readCredentials, identifyCaller, mayAttestUnauthenticated, parseScorePath, parseDidHash,
rateLimited, clientKey, adminTokenPolicyError, runningCommit,
parseTrustedProxies, parseRequestTarget, readScopes, mayUse, weakCredentials, MIN_TOKEN_LENGTH, ATTEST_MAX_BODY_SIZE,
} = require('./http-helpers');
Expand Down Expand Up @@ -435,6 +435,10 @@ const NOBODY_NAMED = () => undefined;
// A transaction hash as a caller may send it, in either case.
const TX_HASH = /^0x[0-9a-fA-F]{64}$/;

// How old a reading of the chain's clock an epoch's per-agent steps and the read routes take: each read it one round
// trip at a time, against a margin of minutes. The epoch's own reading, at its start, is always fresh.
const CHAIN_TIME_REUSE_MS = 5_000;

/**
* How the checker reads a proposal's evidence (evidence-as-of.js). With a payment chain on, at each
* whole-minute cut-off in the half hour before it (payment-chains.auditCuts), since the proposer chose its
Expand Down Expand Up @@ -1967,7 +1971,7 @@ async function runEpochInner() {
// One that starts to count after this evidence time and before the proposal can land: the checker reads the
// evidence at the proposal's own time, so it would count it where this does not. Proposed next epoch.
if (!cfg.checkerMode && chosen.some(negativeHold.isPayerNegative) && negativeHold.startingBetween(
chosen, evidenceCutMs, (await chain.getLatestBlockTimestamp()) * 1000 + proposeMarginMs, negativeHoldCfg,
chosen, evidenceCutMs, (await chain.getLatestBlockTimestamp({ maxAgeMs: CHAIN_TIME_REUSE_MS })) * 1000 + proposeMarginMs, negativeHoldCfg,
).length) {
console.log(`[oracle] ${didHash.slice(0, 10)}… a payer negative starts to count before a proposal could land, skipping`);
agentsHeldByNegative++;
Expand All @@ -1979,7 +1983,7 @@ async function runEpochInner() {
// landing after midnight, it was audited against a reading it was never given. So a linked agent
// whose snapshot would change before its proposal could land is proposed next epoch instead.
if (!cfg.checkerMode && external.configured() && hasLink(didHash)) {
const landsByMs = (await chain.getLatestBlockTimestamp()) * 1000 + proposeMarginMs;
const landsByMs = (await chain.getLatestBlockTimestamp({ maxAgeMs: CHAIN_TIME_REUSE_MS })) * 1000 + proposeMarginMs;
if (reviewers.snapshotOf(Math.floor(scoringNowMs / 1000)) !== reviewers.snapshotOf(Math.floor(landsByMs / 1000))) {
console.log(`[oracle] ${didHash.slice(0, 10)}… its external factor's snapshot changes before a proposal could land; proposing next epoch`);
continue;
Expand Down Expand Up @@ -2297,7 +2301,7 @@ async function runEpochInner() {
console.log(`[oracle] ${didHash.slice(0, 10)}… a transaction from this wallet has not been seen mined; proposing next epoch`);
continue;
}
if (cutTooOld((await chain.getLatestBlockTimestamp()) * 1000, evidenceCutMs)) {
if (cutTooOld((await chain.getLatestBlockTimestamp({ maxAgeMs: CHAIN_TIME_REUSE_MS })) * 1000, evidenceCutMs)) {
console.log(`[oracle] ${didHash.slice(0, 10)}… its evidence was chosen too long ago to propose; proposing next epoch`);
continue;
}
Expand Down Expand Up @@ -2517,6 +2521,13 @@ function saveSoon() {

// ---- HTTP API --------------------------------------------------------------

// The answer to an error a write route's own checks did not catch (http-helpers.uncaughtReply), with its words logged.
function answerUncaught(res, err, route) {
const reply = uncaughtReply(err);
if (reply.log) console.warn(`[oracle] ${route} failed: ${reply.log}`);
return json(res, reply.status, reply.body);
}

// 32MB of serialized evidence responses. The revision token is the payment-event array
// itself: the store replaces it on every change, so nothing has to remember to
// invalidate this, and a case it somehow missed degrades to a cache miss rather than to
Expand Down Expand Up @@ -3853,7 +3864,7 @@ async function handleRequest(req, res) {
});
} catch (err) {
metrics.inc('attestRejectedOther');
return json(res, bodyErrorStatus(err), { error: err.message });
return answerUncaught(res, err, '/attest');
}
}

Expand Down Expand Up @@ -3965,7 +3976,7 @@ async function handleRequest(req, res) {
let nowMs = Date.now();
if (getPaymentEvents(didHash).some(negativeHold.isPayerNegative)) {
try {
nowMs = (await chain.getLatestBlockTimestamp()) * 1000;
nowMs = (await chain.getLatestBlockTimestamp({ maxAgeMs: CHAIN_TIME_REUSE_MS })) * 1000;
} catch { /* this host's clock */ }
}
const events = evidenceAt(didHash, paymentChains.cutFor(nowMs, paymentChainsCfg));
Expand Down Expand Up @@ -4025,7 +4036,7 @@ async function handleRequest(req, res) {
if (replyKey) rememberReply(caller, replyKey, { didHash, flags: raised });
return savedReply(res, durable, { didHash, flags: raised });
} catch (err) {
return json(res, bodyErrorStatus(err), { error: err.message });
return answerUncaught(res, err, '/flag');
}
}

Expand Down Expand Up @@ -4070,7 +4081,7 @@ async function handleRequest(req, res) {
if (replyKey) rememberReply(caller, replyKey, { didHash, ...result });
return savedReply(res, durable, { didHash, ...result });
} catch (err) {
return json(res, bodyErrorStatus(err), { error: err.message });
return answerUncaught(res, err, '/flag/resolve');
}
}

Expand Down Expand Up @@ -4118,7 +4129,7 @@ async function handleRequest(req, res) {
metrics.inc('linksCreated');
return savedReply(res, durable, { didHash, agentId: String(agentId), operator, linked: true });
} catch (err) {
return json(res, bodyErrorStatus(err), { error: err.message });
return answerUncaught(res, err, '/link');
}
}

Expand Down Expand Up @@ -4249,7 +4260,7 @@ async function handleRequest(req, res) {
// epoch path removes, in the place people look to explain it.
//
// One extra chain read per request, on an endpoint that already makes several.
const scoringNowMs = (await chain.getLatestBlockTimestamp()) * 1000;
const scoringNowMs = (await chain.getLatestBlockTimestamp({ maxAgeMs: CHAIN_TIME_REUSE_MS })) * 1000;
const held = evidenceAt(didHash, paymentChains.cutFor(scoringNowMs, paymentChainsCfg));
const standingsReady = await previewStandingsReady(held, scoringNowMs);
if (!standingsReady.ready) {
Expand Down
Loading
Loading