← Back to home

Architecture

Parity

Tokenized stock verification on Solana. How the system answers without making a single external call at visit time.

1. The problem

The same US share exists on Solana as several tokens, from different issuers, and they are not interchangeable. They trade in separate pools, carry different issuer powers, and some of them cannot be sold at all.

Every interface shows a price and a buy button. None of them shows whether the issuer can freeze that balance, whether they can move the token out of a wallet without the holder's signature, or what exiting the position actually costs.

The engineering problem is this: answer those three questions for any ticker, in under a second, with no wallet connected, without spending an API call per visit, and without ever showing stale custody data.

2. The numbers

Everything below was measured against Solana mainnet. The scripts that produced these figures are in the repository and the raw output is committed under data/.

32
tokens in the verified registry
96
Jupiter quotes per collection run (32 tokens × 3 sizes)
15 min
interval between collection runs
1.5 s
deliberate wait between each aggregator call
0
external calls on a normal visit to the site
77
tests, none of which require network
30 of 32
tokens can be frozen by their issuer
16 of 32
carry a permanent delegate: the issuer moves tokens without the holder's signature
13 of 32
returned no route at all: they show a price and cannot be traded
$132
real entry cost on a $1,000 order in AMDx

3. The design

Three independent paths. What matters is that the one on the right, the visit, crosses no external boundary.

COLLECTION — EVERY 15 MINGitHub ActionsJupiter96 quotes, 1.5 s apartDaily JSONLcommit + pushBUILD — ON EVERY DATA COMMITVercel buildreads registry, snapshotsand custody via RPC1 page per ticker pre-generatedREAD — ON EVERY VISITVisitorCDNStatic HTMLZERO EXTERNAL CALLSRPC · Jupiter · DBexternal boundary

Keeping the three apart is what stops a traffic spike from ever touching the RPC node or the aggregator. A visitor reads HTML that already existed before the visit happened.

4. The decisions

Every decision has a price. Below is what I chose, what I rejected, why, and what it costs.

01. Git is the database

Chose
Each collection run appends lines to that day's JSONL file and commits it to the repository.
Over
Postgres, or any hosted database.
Because
The data is append-only, it is small, and its value depends on being verifiable by a third party. Git gives timestamps I do not control, free hosting, and an audit trail without writing one. Any figure published on the site can be checked against the commit that produced it.
Price I pay
There are no queries. To answer how AMDx liquidity moved over three weeks I read and parse files. There are no indexes. Past a certain volume this stops working.

02. No external calls on the read path

Chose
One page per registry entry, generated ahead of time. Unknown tickers are rejected before anything reaches the network.
Over
Fetching live quotes on every visit.
Because
Free-tier RPC and the public Jupiter tier both have rate limits. A traffic spike would either cost money or fail exactly when the most people are looking. A page that is fifteen minutes old beats a page that will not load.
Price I pay
Data is only as fresh as the last build. And a token outside the registry has no answer, which is also a safety property, but it is still a limitation.

03. Two freshness policies in one view

Chose
Liquidity comes from committed snapshots. Custody is read from the RPC node through the adapter.
Over
One uniform cache policy for everything.
Because
The two data types fail differently. Liquidity moves constantly, and a fifteen-minute-old number is acceptable as long as it is labelled. Custody almost never changes, but when an issuer enables a freeze authority, showing the old value is the worst error this product can make, because that is precisely the warning the user came for.
Price I pay
The page mixes two timestamps. That has to be shown to the user, or it misleads.

04. Pure core, I/O only at the edges

Chose
All financial logic lives in src/core as pure functions with no I/O. Network calls happen only in src/adapters and pass plain data inward.
Over
Functions that fetch and compute in the same place.
Because
Money-touching paths need property tests. A function that makes a network call cannot be run ten thousand times against generated input. With the split, all 77 tests run with no network at all.
Price I pay
More files, and a mapping layer between adapter data and core types.

05. Self-imposed rate limiting at 1.5 seconds

Chose
A fixed 1,500 ms sleep between every quote, inside the job.
Over
Parallel requests, or retrying on 429.
Because
The job has a fifteen-minute window and needs about three. Spending time is free. Getting blocked on Jupiter's public tier is not. Slow and certain beats fast and rate-limited.
Price I pay
A run takes minutes instead of seconds. If the registry grows to 300 tokens, that is 900 quotes at 1.5 s, or 22 minutes, which overruns the window. This decision has a known expiry date.

06. Concurrency handled by git, not by a lock

Chose
An Actions concurrency group with cancel-in-progress false, a rebase with autostash before pushing, and an early exit when there is no new data.
Over
A lock table or a queue.
Because
There is exactly one writer and the data is append-only per day. Git's own conflict handling covers the only real race, which is another commit landing between checkout and push.
Price I pay
If a run ever exceeds fifteen minutes, runs queue instead of overlapping, and the spacing of the series starts to drift.

5. What breaks

Including what is unresolved today. An architecture page that only lists what went right is worth nothing.

GitHub's scheduler is not punctual

GitHub documents that scheduled workflows can be delayed or dropped during peak load. That leaves the series with irregular spacing and gaps. It matters because the site presents the series as evidence. The honest part is that every record carries its own capture timestamp, so a gap is visible rather than hidden. The unresolved part is that nothing alerts when one happens.

Collector failure is silent

If the job fails, because Jupiter changes a response shape, because the runner gets blocked, or because the push is rejected, the site keeps serving the last build with no sign that the series stopped. Today the only signal is a GitHub notification, which depends on someone reading it.

Building while the RPC node is down

Custody is read live at build time. If the node is unavailable at that moment, the correct behaviour is for the build to fail rather than publish custody data of unknown age. This is the kind of failure that only shows up the day it happens.

Registry drift

A mint added to the registry arrives with no history. And if an issuer changes a power between two builds, the site shows the old value until the next build, which is exactly the case the product exists to prevent.

Jupiter is a single source

Exit cost is whatever the aggregator answers. If its routing changes or gets something wrong, Parity publishes that as fact. There is no second source to cross-check against.

6. What I would change at 100x

Scenario: 10,000 tracked tokens instead of 32, and 50,000 visits a day with a peak of 500 per second.

What survives unchanged

The read path. Static pages on a CDN do not care about 50,000 visitors or the peak. That side is already solved by the current design.

What breaks first

The collector. Ten thousand tokens times three sizes times 1.5 seconds is twelve and a half hours per pass. The fifteen-minute cadence becomes impossible before anything else goes wrong.

In the order I would change them

  1. 1

    Drop the single cadence. Tokens are not equal: a mint with no route and no volume does not need a quote every fifteen minutes, a liquid one does. Tiered cadence, with hot tokens every fifteen minutes and the long tail once a day.

  2. 2

    Remove the fixed sleep and move to a paid tier with a declared rate limit and controlled concurrency, so a pass is bounded by the rate limit rather than by sleeping.

  3. 3

    Take the bulk out of git. Ten thousand tokens across 96 runs a day grows the repository by hundreds of megabytes a week and makes a clone unusable. Snapshots move to content-addressed object storage, and only the daily digest hash stays committed. The audit property survives, the weight does not.

  4. 4

    Stop rebuilding every page on every data commit. At ten thousand pages that stops adding up. Liquidity moves to incremental regeneration per page, custody stays at build time.

This page describes the system as it stands today, including what is still unresolved. The figures come from mainnet measurement and move over time.