Architecture
The packages, what each one owns, and the path a quote takes from a pool read to a submitted transaction.
Zerochord is a pnpm workspace. Six libraries, two applications, one Aiken project, and one configuration file per Cardano network.
Nothing in the codebase branches on a network name to decide behaviour. Every address,
script hash, policy id, endpoint and protocol reference comes from config/<network>.json.
Layout
onchain/ Aiken validators. The settlement validator for mixed routes.
packages/core Networks, configuration, chain providers, assets, Plutus codec, CIP-20 tagging
packages/venues Per venue adapters: pool discovery, datum decoding, swap arithmetic
packages/quote Path enumeration, exact split routing, the savings claim
packages/oracle Pyth Lazer client, freshness and deviation guards
packages/tx Transaction construction for every venue and for settlement
apps/web The interface
apps/cli Operator, deployment, audit and measurement tool
config/ One file per network. Everything network specific lives here.
docs/ This documentation site
dune/ Queries that surface the tagged activityWhat each package owns
Prop
Type
apps/web is the browser interface, built on Vite, React and TanStack Router, with wallet
access through Weld. apps/cli is cardano-swap, the operator, deployment, audit and
measurement tool.
The path a quote takes
Configuration is loaded and validated
loadNetworkConfig(network) reads config/<network>.json, validates it against a Zod
schema, and recomputes every asset's CIP-14 fingerprint from its policy id and asset name.
A single altered character in a policy id throws at load rather than producing a wrong quote
later.
The chain provider is built
The configuration names a primary provider. The command line builds it through
createProviders(network). The browser builds Koios directly, because a Blockfrost project
id compiled into a bundle every visitor downloads is a published secret.
Adapters are built for the venues this network enables
A venue that is disabled, or whose pool script hash is null on this network, is skipped with its reason recorded. A network where only one venue is deployed is a real situation, not an error.
Pools are discovered and stamped with one tip
Every adapter discovers its pools concurrently. The reads land at slightly different moments, so all pools are restamped with the newest tip of the reads. A quote assembled from two different blocks is not comparable against its own baseline, and the engine refuses one.
The engine produces a quote
QuoteEngine.quote(pools, request) enumerates paths, reduces each to one effective pool,
solves the split, then requotes the winning allocation hop by hop with each venue's own
arithmetic. The last step is the number you are shown.
See Routing.
A builder turns the quote into a transaction
@cardano-swap/tx takes the quote itself, so the minimum written on chain is the minimum
the quote carries. There is no second copy of that number. Every builder attaches the CIP-20
product tag, and the tag helper refuses a message that does not name the project.
The user signs once, and the transaction is submitted
Building and submitting are separate calls. The transaction is signed and complete before anything is sent, so the same path can be exercised without spending anything.