# Architecture (/developers)



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 [#layout]

```text
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 activity
```

## What each package owns [#what-each-package-owns]

<TypeTable
  type="{
  &#x22;@cardano-swap/core&#x22;: {
    type: &#x22;foundation&#x22;,
    description: &#x22;Network identity, configuration loading and validation, the Koios and Blockfrost chain providers, the asset registry with CIP-14 fingerprint recomputation, the Plutus data codec, and CIP-20 metadata construction.&#x22;,
  },
  &#x22;@cardano-swap/venues&#x22;: {
    type: &#x22;market data&#x22;,
    description: &#x22;One adapter per venue. Each discovers its pools by payment credential, decodes each pool datum, and quotes a swap in the venue's own integer arithmetic.&#x22;,
  },
  &#x22;@cardano-swap/quote&#x22;: {
    type: &#x22;routing&#x22;,
    description: &#x22;Candidate path enumeration, reduction to effective pools, the exact split solve, the integer requote, the direct route baseline and the saving.&#x22;,
  },
  &#x22;@cardano-swap/oracle&#x22;: {
    type: &#x22;price reference&#x22;,
    description: &#x22;The Pyth Lazer client, signed update parsing and Ed25519 verification against the on-chain trusted signers, the freshness check, the deviation guard, and the withdrawal redeemer.&#x22;,
  },
  &#x22;@cardano-swap/tx&#x22;: {
    type: &#x22;transactions&#x22;,
    description: &#x22;Transaction construction over Lucid Evolution: the Dano Finance pool spend, the Minswap V2 order and cancel, the SundaeSwap order, the settlement lock, claim and refund, the Pyth zero withdrawal, and the product tag every builder passes through.&#x22;,
  },
}"
/>

`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 [#the-path-a-quote-takes]

<Steps>
  <Step>
    ### Configuration is loaded and validated [#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.
  </Step>

  <Step>
    ### The chain provider is built [#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.
  </Step>

  <Step>
    ### Adapters are built for the venues this network enables [#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.
  </Step>

  <Step>
    ### Pools are discovered and stamped with one tip [#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.
  </Step>

  <Step>
    ### The engine produces a quote [#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](/developers/concepts/routing).
  </Step>

  <Step>
    ### A builder turns the quote into a transaction [#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.

    See [Building transactions](/developers/internals/transaction-building).
  </Step>

  <Step>
    ### The user signs once, and the transaction is submitted [#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.
  </Step>
</Steps>

## Read next [#read-next]

<Cards>
  <Card title="Execution classes" href="/developers/concepts/execution-classes">
    The distinction that decides what the product can promise.
  </Card>

  <Card title="Routing" href="/developers/concepts/routing">
    How the engine picks a route and why it requotes.
  </Card>

  <Card title="Command line" href="/developers/reference/command-line">
    Every command and flag.
  </Card>

  <Card title="Local development" href="/developers/local-development">
    Toolchain, install, build, test.
  </Card>
</Cards>