Docs/How it works/Architecture

Fiangshi architecture

This page explains how Fiangshi is built, so an integrator or auditor can trust it. It covers every component, every outside service it talks to, where data is kept, and what happens when each part fails. Every threshold below is copied from the source file named next to it. If this page and the code disagree, the code is right, and that is a bug in this page.

The map

In words: an AI tool (through MCP or HTTP) or a person (on the site) asks about a paid URL. Inside the Fiangshi server the request goes through eight steps: probe, null-payee gate, signals, score, model advice, six rules, decide and receipt. The seller, Surf, SERV, Dolphin and the ledger are each used by one step. The verdict, its evidence and a receipt id go back, and the agent's own wallet pays, or does not.

See it working

The pictures on this page are working models: they move through the same steps the code takes. On the site at /architecture they are animated; in the repository the text describes them.

What each step does

1. Probe

src/adapters/probe.ts sends one GET with no payment header and reads the HTTP 402 answer: the headers and the JSON body. It accepts x402 v1 and v2 shapes. It checks each payment option on its own, so one malformed option cannot hide a valid Base option. The terms are hashed as canonical JSON (sorted keys, src/core/canonical.ts), giving terms_hash. A probe that times out, returns something other than 402, or has no parseable Base option gives no verdict (probe failed), never ALLOW.

2. Null-payee gate (rule I, null_payee)

src/core/v6.ts runs before anything is spent. It blocks when the payTo address is:

• the zero address, in any spelling;
• a known burn address (BURN_SINKS);
• the payment token's own contract (paying a token contract burns the money);
• a mixed-case address that fails its EIP-55 checksum (keccak-256 is implemented in the file, with no dependency).

A blocked endpoint costs $0.00. No data call or model call is made, and a receipt is still sealed, so the BLOCK can be verified later.

3. Signals: where the facts come from

The signals are: wallet age, transaction count, first funder, how many other catalog sellers share that funder (funder_fanout), distinct payers, repeat payers, total received, the top payer's share, dormancy and identity claims. Each one carries a quoted line of evidence. A value that is negative, not a number, in the future, or self-funding is turned into "missing" (sanitize in src/core/score.ts), and a missing value triggers rule VI (silence), which gives REVIEW. A data error never gives BLOCK.

4. Score

src/core/score.ts. Each component is in [0, 1]. A missing optional component (identity) has its weight removed and the rest re-scaled, so having no claim is never a penalty.

Bands from the score: 80 or more is ALLOW, 50 to 79 is REVIEW, under 50 is BLOCK.

5. Model advice

Two models run in parallel and neither can decide alone.

• SERV Reasoning (src/adapters/serv.ts) gets the signals and their evidence and must answer in strict JSON (response_format json_schema). The answer is checked by validateModelOutput in src/core/decide.ts: each cited signal must exist, and each quote must be an exact substring of the stored evidence. If the check fails, it is retried once with stricter instructions. If it fails again, the verdict is marked degraded and capped at REVIEW. A model BLOCK is capped at REVIEW too, because a model is not a machine-checkable reason.
• Dolphin (src/adapters/dolphin.ts) turns the seller's own prose into typed identity fields (organisation, product). It has no say on the verdict. It has 12 s per try and one retry; if it times out, the receipt says enrichment: incomplete and the band is not changed.

Model replies are cached by a hash of the exact evidence they saw, so the same evidence never pays twice, and changed evidence asks again.

6. The six rules (vows)

src/core/vows.ts. They run after the model and can only lower the band. When several fire, the most severe one is reported; ties go to the order below.

7. Decide

src/core/decide.ts: final band = the lowest of the score band, the model band and the deciding rule's band. ALLOW needs all three to agree. The model can only lower the band, never raise it.

8. Receipt and ledger

src/core/receipt.ts writes a receipt with: payee, url, terms_hash, price, band, score, vow_fired, evidence quotes, model verdict and degraded flag, snapshot_id, checked_at, chain: "eip155:8453", prev_hash, receipt_hash and settlement. receipt_hash is the sha256 of the canonical JSON of every other field, and prev_hash links it to the receipt before it in data/ledger.jsonl. Changing any field breaks GET /v1/verify.

Receipts are tamper-evident through the hash chain. They are not signed with a private key: Fiangshi holds no keys at all. Anyone can recompute a hash.

src/ledger/drift.ts flags a payee whose band crosses 50 or 80, whose payee address rotates, whose funder changes, whose price moves more than 10% (PRICE_DRIFT), or which wakes up after 60 or more dormant days (DORMANCY_DAYS). A verdict older than 72 h (FIANGSHI_POLICY_TTL_HOURS) is stale and must be checked again.

Outside services

The HTTP server itself never calls Surf for the census: the census is built from committed files at startup. Only the cold check calls Surf at request time, and only on the paid route.

Storage

There is no database server. There are no accounts and no user records.

Security and trust model

• No custody. Fiangshi never holds funds, signs transactions, or sends them. It has no private key. The paid routes receive payment to an address the operator sets (FIANGSHI_PAYTO), which must itself pass rule I.
• Fail closed. Missing data, a timeout, a schema violation, a model failure or a budget refusal gives REVIEW. Nothing defaults to ALLOW. BLOCK always names a rule and quotes evidence.
• Rules over model. A model answer is advice. It can lower a verdict, never raise it, and its quotes are checked word for word against stored evidence, so it cannot invent facts.
• No scripts on the site. Every HTML page is sent with Content-Security-Policy: default-src 'none'. The site uses one functional cookie only to remember that the first-visit tour was closed (see the Legal page). There is no tracking.
• Input handling. Only http(s) URLs up to 2,000 characters are probed. Every request handler is wrapped, so one failing request cannot stop the server. Markdown pages escape all raw HTML.
• Reproducible numbers. Every number in the documents comes from a committed script. npx tsx scripts/numbers.ts --check (accept gate G12) fails the build if a document disagrees.

Budgets and limits

Configuration

The full list, with defaults, is in .env.example.

Failure modes

What it does not do

• It does not pay, sign, hold or move money.
• It does not cover chains other than Base (eip155:8453).
• It does not promise a seller is honest. ALLOW means no rule fired and the evidence is strong today. It is advice for the next 72 hours.
• It does not settle real payments in this build: settlement is dry-run.
• It does not track visitors.