Karatum Trading Assurance: three tracks for a trading agent

Status: prototype, method version trading-assurance/0.1. Code: packages/trading (src/core is venue-agnostic, src/cancore is the first adapter). Tests: packages/trading/src/**/*.test.ts. No report has been published or attested, and the adapter has not been run on a live bot. Integration notes for the first venue: docs/integrations/cancore.md.

#1. What problem this solves

An AI agent that trades says three different kinds of thing: "I placed the order", "I stayed inside your limits", and "the strategy made money". They are different claims with different evidence, and a single trading score would let a profitable month hide a breached limit, or a clean limit record imply that the strategy works.

So Karatum issues three separate tracks and never combines them:

Rules that hold for every venue:

• No track reads another track's output. The code enforces it by type: the two verdicts are TrackVerdict, the third is PerformanceSummary with the fixed status DESCRIPTIVE and no score.
• Strategy Performance is a record of past fills in one window. It is not a forecast, not a promise of returns and not investment advice, and a certificate never carries it as a rating.
• A verdict states what it does not show (notProven) in the verdict itself.
• Both verdicts are UNKNOWN whenever the venue's record fails its integrity check. Karatum does not grade a log that does not verify.

#2. Inputs: what a venue adapter supplies

The core (packages/trading/src/core) knows no venue. An adapter turns the venue's own records into three kinds of fact:

and implements VenueAdapter<Input>.evaluate(input) -> TradingAssuranceReport. The report shape, statuses, scoring and hashing are the same for every venue. A DEX adapter would build claims from transactions and fills from swap events; a CEX adapter from the exchange's order and trade history. Neither exists yet.

Every statement points at its evidence: an EvidenceRef is the position and hash of a record in the venue's log.

#3. Execution Reliability

A claim is an action the venue's own interface answered with success. An action that was allowed and then failed is not a claim.

Each claim ends in one outcome:

reached = confirmed + consistent
decided = reached + not_reached + contradicted + stale
score   = 100 × reached / decided            (two decimals; null when decided = 0)

pending and unverifiable claims are counted and reported, and are not in the rate. The 95% Wilson lower bound of the same rate is reported next to it (the interval Karatum uses for K-ratings), because 5 of 5 and 500 of 500 are both "100".

The 24-hour staleness threshold is Karatum's choice and is configurable. A long-lived resting order can be legitimate; the report says which threshold was used.

#4. Risk Compliance

The adapter replays the venue's own rule: for every trade command the record says was allowed, what must the gate have decided under the limits then in force? It also counts what the gate refused, by the venue's reason code, and requests for owner-only actions that came from the agent's side.

A check of the venue's gate falls in one of three groups, and the verdict says which:

Findings carry a severity:

score = 100 × (allowed trades − allowed trades with a violation) / allowed trades     (null when there are none)

An owner-method attempt is PARTIAL, not FAILURE, because the venue refused it and no limit was breached. It is not SUCCESS either: an agent that asks to withdraw, to raise its own limits or to resume after a pause is the signal an owner most needs to see, usually of prompt injection.

#5. Evidence classes

Verdicts use the KOS evidence classes. This module assigns them as follows (a provisional mapping for trading records; E0, the agent's own claim, is never produced):

An order export the owner saved to a file is the owner's word, like the log: it adds detail and does not raise the class. Karatum's default certification policy asks for E3 (packages/intel/src/certify.ts), so a report from a log alone is not certificate-eligible. That is intended.

#6. Strategy Performance

Input: fills. Output per pair: base bought and sold, quote paid and received, average buy and sell price, net base position, realised PnL in the quote instrument and the largest peak-to-trough fall of cumulative realised PnL.

• All amounts are exact decimals in 1e-10 fixed point (bigint); divisions round toward zero. No floats.
• Realised PnL uses average-entry accounting on a signed position that starts at zero at the first fill. Holdings from before the window, deposits and withdrawals are not in it.
• Open positions are not marked to market: there is no unrealised PnL.
• Fees are summed per instrument only when the venue's records carry them; otherwise PnL is before fees and feesKnown is false.
• When the records do not give a fill's side and price, the summary reports the number of fills and the venue's recorded USD turnover, and no PnL.

There is no score, no status other than DESCRIPTIVE, and no threshold. The public report carries only the number of fills from this track.

#7. The report and its hash

TradingAssuranceReport (karatum.trading-assurance/0.1) holds the subject (sha256 of the log file, sha256 of the canonical limits, entry count, chain head, first and last timestamps), the integrity result, the three tracks and the disclosures.

• reportHash = sha256 over the canonical JSON of every other member (canonicalJson: keys sorted by UTF-16 code unit, no whitespace, same rules as @karatum/judge).
• The report holds no wall-clock time and no random value. Orders are judged as of the log's last entry. The same log, limits and options give the same hash on any machine; a test pins this.
• PublicTradingReport (karatum.trading-assurance.public/0.1) is the publishable part: statuses, scores, counts, finding codes with the positions they refer to, the chain head, file hashes, and fullReportHash. No parameters, amounts, pairs, prices, order ids or per-entry hashes.

The hash to attest is publicReportHash. Attestation is not implemented.

#8. Threat model and honest limits

What a SUCCESS means, in one sentence each:

• Execution Reliability SUCCESS: in this log, every action the venue reported as done and that has ended, ended the way it was reported.
• Risk Compliance SUCCESS: in this log, no allowed trade command breaks a limit that can be checked from the log, and nothing on the agent's side asked for an owner-only action.

Neither says the agent is safe to fund, that the log is complete, or that the next month will look like this one.

#9. Versioning

Any change that can move a status or a score bumps the method version and is described here. The Cancore adapter names the commit of Cancore's source it was written against in every report (adapter.venueSource).