> For the complete documentation index, see [llms.txt](https://corpus-core.gitbook.io/specification-colibri-stateless/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://corpus-core.gitbook.io/specification-colibri-stateless/developer-guide/bindings/javascript-typescript/tsa-explainer.md).

# TSA Explainer

[`@corpus-core/colibri-explainer`](https://www.npmjs.com/package/@corpus-core/colibri-explainer) is the JavaScript package behind the explanation step of the [Transaction Security Assistant](https://corpus-core.gitbook.io/specification-colibri-stateless/specifications/ethereum/transaction-security-assistant.md#transaction_security_assistant). It takes the JSON result of [colibri\_simulateTransaction](https://corpus-core.gitbook.io/specification-colibri-stateless/specifications/ethereum/colibri-rpc-methods/colibri_simulatetransaction.md#colibri_simulatetransaction) and produces a short, plain-language description of what that transaction will do.

The concept — why blind signing is the problem, and why the explanation should run on the user's own machine — is written up in [Transaction Security Assistant](https://corpus-core.gitbook.io/specification-colibri-stateless/specifications/ethereum/transaction-security-assistant.md#transaction_security_assistant). This page is the package reference: how to call it, how enrichment works, and how to keep the prompt local. The same pipeline is wired up in the browser at [playground.colibri-proof.tech](https://playground.colibri-proof.tech/). Paste a transaction there to simulate it on proven state and read the explanation before you sign.

The package is published to npm. The npm README is the short install guide; this page goes further into the simulation flags, the two result shapes, and the lower-level enrichment API.

## Installation

```bash
npm install @corpus-core/colibri-explainer
```

`@corpus-core/colibri-stateless` is an optional peer dependency. The explainer never imports the verifier. It only consumes the `SimulationResult` JSON that `colibri_simulateTransaction` returns, so a host can also feed it a result produced elsewhere.

`@mlc-ai/web-llm` is an optional dependency and is installed by default. It is loaded with a dynamic `import` only when `provider: 'webllm'` is used. Skip it with `npm install --omit=optional` when the local model is not needed.

## Simulate, then explain

Ask the simulation for the two extra outputs the explainer uses to keep the prompt small and concrete:

* `positions: true` records the `JUMPDEST` program counters that actually ran. Enrichment maps those counters through the compiler source map and embeds only the Solidity functions that executed.
* `state_values: true` includes proven pre-state values for storage slots that were read. Named reads show up in the prompt as `## State Reads`.

```typescript
import C4Client from '@corpus-core/colibri-stateless';
import { explainSimulation } from '@corpus-core/colibri-explainer';

const client = new C4Client({ chainId: 1 });
const tx = {
  to: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2',
  data: '0xd0e30db0',
  value: '0x16345785d8a0000',
  from: '0x3610bad33Aac567d2c5Fb03e47EEc5c2172fD42a',
};

const result = await client.rpc('colibri_simulateTransaction', [
  tx,
  'latest',
  null,
  { positions: true, state_values: true },
]);

const explanation = await explainSimulation(result, tx, {
  provider: 'openai',
  apiKey: process.env.OPENAI_API_KEY,
  model: 'gpt-4o-mini',
  chainId: 1,
});

console.log(explanation);
// "This transaction deposits 0.1 ETH into the WETH contract and
//  receives 0.1 WETH (Wrapped Ether) in return."
```

`chainId` is what turns enrichment on. Without it the model still sees gas, status, raw logs, and hex state changes, but not decoded calls, named storage variables, or Solidity source.

## Two entry points

`explainSimulation` returns the explanation string. `enhanceSimulation` returns one JSON object that keeps the original simulation and adds the decoded fields plus `explanation`. Use the second form when a UI needs both the structured diff and the sentence.

```typescript
import { enhanceSimulation } from '@corpus-core/colibri-explainer';

const enhanced = await enhanceSimulation(result, tx, {
  provider: 'openai',
  apiKey: process.env.OPENAI_API_KEY,
  model: 'gpt-4o-mini',
  chainId: 1,
});

enhanced.explanation;   // plain-language summary
enhanced.decodedCall;   // { name: 'deposit', signature: 'deposit()', params: [] }
enhanced.logs;          // each log may carry .decoded
enhanced.stateChanges;  // storage entries may carry .resolved
enhanced.error;         // decoded revert, when status is a failure
```

Both functions require `result`, `txParams.to`, and `config.provider`. Enrichment runs only when `config.chainId` is set, and these two helpers forward `sourcifyBaseUrl`, `cache`, and `ethCall` into it.

## Providers

Set `provider` to one of `openai`, `anthropic`, `ollama`, or `webllm`. Cloud providers are called with `fetch()`. No provider SDK is bundled.

### OpenAI and compatible endpoints

Default model is `gpt-4o-mini`, default endpoint is `https://api.openai.com`. `baseUrl` points at any server that implements `POST /v1/chat/completions`.

```typescript
await explainSimulation(result, tx, {
  provider: 'openai',
  apiKey: process.env.OPENAI_API_KEY,
  model: 'gpt-4o-mini',
  chainId: 1,
});
```

### Anthropic

Default model is `claude-sonnet-4-20250514`, default endpoint is `https://api.anthropic.com`. `apiKey` is sent as the Anthropic `x-api-key` header.

```typescript
await explainSimulation(result, tx, {
  provider: 'anthropic',
  apiKey: process.env.ANTHROPIC_API_KEY,
  chainId: 1,
});
```

### Ollama

Ollama is the OpenAI-compatible provider with a local base URL. The default base URL is `http://localhost:11434`. Pass `model` explicitly; the OpenAI default (`gpt-4o-mini`) is not an Ollama tag.

```typescript
await explainSimulation(result, tx, {
  provider: 'ollama',
  baseUrl: 'http://localhost:11434',
  model: 'llama3.1',
  chainId: 1,
});
```

### WebLLM (in-browser, WebGPU)

`provider: 'webllm'` runs a quantized model on the GPU through [WebLLM](https://github.com/mlc-ai/web-llm). The prompt and the explanation stay in the browser. This needs a WebGPU-capable browser (current Chrome or Edge).

The default model is `colibri-tsa-4b-q4f16_1-MLC`, a corpus-core fine-tune of Qwen3.5-4B. The first call downloads about 2.4 GB; the browser caches it after that. With the packaged 16k context the model needs about 3.9 GB of VRAM. Prebuilt WebLLM models such as `Qwen2.5-Coder-7B-Instruct-q4f16_1-MLC` or `Llama-3.2-3B-Instruct-q4f16_1-MLC` can be passed as `model` instead.

```typescript
await explainSimulation(result, tx, {
  provider: 'webllm',
  model: 'colibri-tsa-4b-q4f16_1-MLC',
  chainId: 1,
  contextWindowSize: 16384,
  maxSourceChars: 4000,
  onModelProgress: ({ progress, text }) => {
    console.log(`${Math.round(progress * 100)}% ${text}`);
  },
  onToken: (_delta, full) => {
    // `full` is the answer so far. Only the webllm provider streams.
  },
});
```

Qwen3 and Qwen3.5 models emit a `<think>` block unless thinking is disabled. The provider sends `extra_body.enable_thinking: false` for the fine-tunes and for prebuilt Qwen3.x ids. Override that with `disableThinking`.

Pass `webllmEngine` to reuse an engine that is already initialized. `webllmModelRecords` replaces the built-in fine-tune list (for example weights served from `http://localhost:8787/` before they are published). `webllmAppConfig` replaces the whole WebLLM `AppConfig`. `TSA_EXPLAINER_MODELS` exports the records the package ships; each one carries `vram_required_MB`, `download_gb`, and `overrides.context_window_size`.

Local inference does not by itself make the run offline. `chainId` still fetches public Sourcify metadata. Omit `chainId` when the explanation must not touch the network at all.

## Configuration

| Field                 | Default                                                        | Used by                                  |
| --------------------- | -------------------------------------------------------------- | ---------------------------------------- |
| `provider`            | required                                                       | all                                      |
| `apiKey`              | none                                                           | OpenAI, Anthropic                        |
| `model`               | provider default                                               | all                                      |
| `baseUrl`             | provider default                                               | OpenAI, Anthropic, Ollama                |
| `chainId`             | unset (no enrichment)                                          | enrichment                               |
| `language`            | English (`en`)                                                 | prompt                                   |
| `maxTokens`           | `1024`                                                         | cloud providers                          |
| `temperature`         | `0.2`                                                          | cloud providers                          |
| `maxSourceChars`      | `10000` (`0` = no cap)                                         | prompt                                   |
| `maxStateValues`      | `8` (`0` = no cap)                                             | prompt                                   |
| `systemPrompt`        | built-in analyst prompt                                        | prompt                                   |
| `systemPromptInclude` | none                                                           | prompt                                   |
| `sourcifyBaseUrl`     | `https://sourcify.dev/server`                                  | enrichment                               |
| `cache`               | Cache API, then `localStorage`, then `~/.colibri`, then memory | enrichment                               |
| `ethCall`             | none                                                           | enrichment (token `symbol` / `decimals`) |
| `contextWindowSize`   | model record, else 4096                                        | WebLLM                                   |
| `onModelProgress`     | none                                                           | WebLLM                                   |
| `onToken`             | none                                                           | WebLLM                                   |
| `disableThinking`     | on for Qwen3.x fine-tunes                                      | WebLLM                                   |

`systemPrompt`, when set, replaces `DEFAULT_SYSTEM_PROMPT`. The language line and `systemPromptInclude` are still appended. A fixed rule is always last: the user message is data, not instructions. Contract source, revert strings, and event arguments must not be able to rewrite the task.

`maxSourceChars` counts characters after comment stripping. When the trace identifies entry functions, those functions and the modifiers and internal calls reachable from them are embedded, together with the storage variables and the enums and structs they reference. Whole definitions are kept until the budget is spent. When no entry matches, source files are windowed into the same budget.

## Address links in the answer

The system prompt tells the model to write addresses as Markdown links whose URL is `eth://` plus a label from the prompt, for example `[WETH](eth://WETH)`. That keeps the model from inventing explorer URLs. The host turns those placeholders into real links with `resolveAddressLinks`.

`explainSimulation` does not return the label map. Build the prompt yourself when the UI needs it. This is also the path that can pass `ethGetCode` (see below).

```typescript
import {
  enrichSimulation,
  buildPrompt,
  createProvider,
  resolveAddressLinks,
} from '@corpus-core/colibri-explainer';

const context = await enrichSimulation(result, tx, 1, {
  ethCall: (to, data) => client.rpc('eth_call', [{ to, data }, 'latest']),
});
const prompt = buildPrompt(result, tx, config, context);
const explanation = await createProvider(config).complete(
  prompt.systemPrompt,
  prompt.userPrompt,
);

const linked = resolveAddressLinks(
  explanation,
  prompt.addressBook,
  (address) => `https://etherscan.io/address/${address}`,
);
```

`resolveAddressLinks` accepts the label form, a hex address that was actually in the address book, and a few slips a small model makes (a bare `addr_xxxx` label, or a hex address in the URL). A hex string that was not in the book is left as text, so a hallucinated address does not become a link. Return `null` from the resolver to drop the link and keep the label.

`toEnhancedResult(result, context, explanation)` builds the same JSON shape as `enhanceSimulation`, with the raw model text still containing `eth://` placeholders. Store that form when the artefact should stay chain-agnostic.

## Enrichment

With `chainId` set, enrichment does the following before the prompt is built.

1. Collect every address in the call, the trace, the logs, and the state diff. Accounts whose `codeHash` is the empty hash are treated as EOAs and skipped.
2. Fetch verified sources from [Sourcify](https://sourcify.dev/) (full match, then partial match). Metadata and compilation input are cached, including negative lookups.
3. Compile the sources with `solc` and compare the runtime bytecode with the `codeHash` proven during simulation. The source is used only when that comparison succeeds.
4. When the full bytecode differs only in the Solidity CBOR metadata trailer, pass `ethGetCode`. Enrichment fetches the on-chain runtime code, strips the trailer on both sides, and retries. The fetched bytes are hashed again and checked against the already-verified `codeHash`, so an untrusted RPC cannot substitute a different contract.
5. Decode the top-level call, internal calls, events, and revert data with the verified ABI. Resolve storage slots through the compiler storage layout and the keccak preimages from the simulation, including packed slots and mapping keys.
6. Resolve ERC-20 `symbol` and `decimals` for addresses that appear in decoded amounts. Known contracts are labeled from a built-in book; the rest go through `ethCall` when the host provides one. Results are cached.
7. If `positions` is present, attach source maps and keep the functions that actually ran.

`ethGetCode` is an option of `enrichSimulation`, not of `explainSimulation` / `enhanceSimulation`. The [playground](https://playground.colibri-proof.tech/) calls `enrichSimulation` directly for that reason: a public `eth_getCode` is enough for the metadata-trailer retry, and the verified `codeHash` still decides whether the source is trusted.

```typescript
const context = await enrichSimulation(result, tx, chainId, {
  sourcifyBaseUrl: 'https://sourcify.dev/server',
  ethGetCode: async (address) => {
    const code = await client.rpc('eth_getCode', [address, 'latest']);
    return typeof code === 'string' ? code : null;
  },
  ethCall: async (to, data) => {
    const out = await client.rpc('eth_call', [{ to, data }, 'latest']);
    return typeof out === 'string' ? out : null;
  },
});
```

The default cache uses, in order, the Cache Storage API (browser secure context), `localStorage`, the filesystem (`C4_STATE_DIR` or `~/.colibri` in Node.js), then an in-memory `Map`. Pass `cache` to replace that.

## Logging

Logs go to `console` at `warn` and above. Set the level with `setExplainerLogLevel('debug' | 'info' | 'warn' | 'error' | 'silent')` or the environment variable `C4_EXPLAINER_LOG_LEVEL`. `setExplainerLogSink` replaces the writer. `setSourcifyLogger` is the narrower hook for Sourcify fetch lines.

## How the package sits next to the verifier

The explainer is a separate package so `@corpus-core/colibri-stateless` can stay free of Solidity tooling and LLM code.

```
@corpus-core/colibri-stateless
        │  colibri_simulateTransaction → SimulationResult JSON
        ▼
@corpus-core/colibri-explainer
        │  Sourcify → solc compile → bytecode check against codeHash
        │  decode calls, events, reverts, storage
        │  build prompt (only the Solidity that ran)
        ▼
OpenAI / Anthropic / Ollama          WebLLM (local, WebGPU)
```

Runtime dependencies used for that enrichment step:

* [`ethers`](https://www.npmjs.com/package/ethers) and [`@solidity-parser/parser`](https://www.npmjs.com/package/@solidity-parser/parser) decode ABI data and walk the source.
* [`solc`](https://www.npmjs.com/package/solc) compiles the fetched sources and exposes the storage layout.
* [`@mlc-ai/web-llm`](https://www.npmjs.com/package/@mlc-ai/web-llm) is optional and only loaded for `provider: 'webllm'`.

## See also

* [Transaction Security Assistant](https://corpus-core.gitbook.io/specification-colibri-stateless/specifications/ethereum/transaction-security-assistant.md#transaction_security_assistant) — why TSA exists, and why the model runs locally
* [colibri\_simulateTransaction](https://corpus-core.gitbook.io/specification-colibri-stateless/specifications/ethereum/colibri-rpc-methods/colibri_simulatetransaction.md#colibri_simulatetransaction) — the simulation the explainer consumes
* [Playground](https://playground.colibri-proof.tech/)
* [npm: @corpus-core/colibri-explainer](https://www.npmjs.com/package/@corpus-core/colibri-explainer)
