Tokenistry
Discuss your architecture

Platform

Tokenization Engine Transaction Engine Eligibility & Compliance Investment Ledger Indexing Engine Custody Integration

Technology

Technology Architecture Quickstart

Company

Institutions Engagement Live demo Discuss your architecture

Architecture

Designed for the failure modes, not the happy path.

Anything can move a token once. Infrastructure earns its place in a regulated stack by what it does on the bad day — when an RPC provider degrades, a block is reorganized, a worker dies mid-submission or a client retries the same instruction twice. This page sets out what each part of Tokenistry Core is accountable for, what it guarantees, and how it behaves when those guarantees are tested.

Request an architecture review See the failure behavior

The stack, layer by layer

Five product modules sit between your product and the chain. The marked band is what Tokenistry ships and maintains; everything above and below it stays under your control. Modules are delivered as signed container images.

architecture // tokenistry core

Runtime topology and ownership boundaries

single-tenant

Customer-controlled

Customer product

Subscriptions, documents, payments, investor experience, issuer workflows

your stack

Tokenistry Core — domain services

Investment Ledger

Effective ownership derived from chain: lots, FIFO consumption, lineage, reallocations, ownership transfers, redemptions, reconciliation

Rustcompiles tocontainer

Tokenistry Core — chain-facing services

Transaction Engine

Durable queue, signing workflow, nonce and fee handling, submission, replacement, confirmation

Rustcompiles tocontainer

Indexing Engine

Block and event ingestion, normalization, reorg handling, backfill and recovery

Rustcompiles tocontainer

Chain & custody adapters

EVM adapters, custody interface, RPC clients — internal, not sold separately

Rustcompiles tocontainerinternal

Tokenistry Core — settlement

Tokenization Engine

ERC-20 + ERC-7943 token, compliance registry, CREATE2 beacon factory — mint, burn, freeze, forced transfer, roles, EIP-712/1271

SolidityFoundrycompiles toEVM bytecode

Customer-controlled

Custody, RPC, database, cloud

Custody workspace, node or RPC provider, PostgreSQL, IAM, network — your accounts, your keys

your accounts

Blockchain / DLT

Settlement plane

external

What each component is accountable for

Every module has one job and one failure story. What each one promises, and what it does when that promise comes under pressure:

tokenistry core // responsibilities and failure behavior
Component Accountable for Under failure
Public API & domain services Authorization, validation, and the versioned contract your product integrates against. An operation that fails validation is rejected at the edge rather than partially applied. Each service holds its own schema and its own database credentials, so a bad migration or a compromised credential is bounded by the service it happened in.
Investment Ledger Effective ownership: lots, FIFO consumption, lineage, reallocations, redemptions. Ownership arithmetic runs inside database transactions with row-level locking, so concurrent transfers serialize instead of interleaving. A crash mid-operation rolls back rather than leaving a half-consumed lot.
Eligibility & compliance Who may hold, enforced by the registry the token reads inside every transfer. The check sits in the transfer path, not in front of it, so an off-chain outage cannot let an ineligible transfer through. A token with no list attached moves nothing at all.
Transaction Engine Durable queue, signing workflow, nonce and fee strategy, submission, replacement, confirmation. Request state is durable before anything is signed, so a worker that dies mid-flight resumes from the record rather than losing or re-issuing the instruction. A stuck transaction is replaced on the same nonce, never duplicated onto a new one.
Indexing Engine Block and event ingestion, normalization, reorg handling, backfill and recovery. Provider degradation slows ingestion rather than corrupting it: the head position is checkpointed, gaps are backfilled on recovery, and a reorg rolls derived events back instead of leaving state asserted that the chain no longer agrees with.
Chain & custody adapters Encoding, signature assembly and chain-specific behavior, behind one interface. Chain and RPC responses are treated as untrusted input, decoded and validated at a single boundary. Past that boundary the invariants are carried in types, so a malformed payload is a rejected message rather than a bad settlement.
Token contracts Settlement: mint, burn, freeze, forced transfer, roles, and transfer restriction. A transfer either meets the contract's conditions or reverts — there is no partial settlement. Upgrade authority sits on the beacon and is held by you, so no Tokenistry release can change a deployed token.
Persistence Single source of truth for ledger, queue and permission state, in your PostgreSQL instance. Your database, your backups, your retention policy and your restore drill. Migrations ship with the image version that requires them, so schema and code move together.
Packaging & deployment Container images, versioned migrations, Helm charts and Terraform modules. A deployment is reproducible from a pinned image digest, which makes a rollback a redeploy of the previous version rather than a reconstruction of an environment.

Services do not share a database in either direction. The ledger owns the ownership and permission schemas, the chain-facing services own transaction and indexing state, and the two meet over versioned service contracts. That boundary is what makes it possible to upgrade one side without coordinating a release of the other — and what keeps a fault in one module from becoming an incident in all of them.

What it is built with

The backend modules are Rust, published as multi-architecture container images and signed with cosign against the immutable version tag. The contracts are Solidity, developed and tested with Foundry and verified on chain. State is PostgreSQL. Packaging is Docker, Helm and Terraform, and integration is over a versioned HTTP API with an OpenAPI specification.

The chain-facing path is long-lived, highly concurrent, and must not lose a signed transaction, so it runs compiled and without a garbage collector — explicit concurrency and predictable memory under sustained load, which is what keeps submission latency and backfill cost bounded as volume grows rather than bursty under it. Settlement is Solidity because it has to be deterministic, testable against real mainnet state before it is deployed, and verifiable on chain afterwards by anyone holding the token.

Two execution environments, two failure models

The system is split where the failure model changes. Off chain, work must survive crashes, retries and unreliable providers. On chain, work must settle deterministically and stay verifiable afterwards. Those are different problems, and conflating them is how tokenization stacks end up asserting ownership the chain does not agree with.

Off chain — the path that must not lose work

Everything between an authorized business operation and a confirmed block runs as Tokenistry Core services in your environment. This is the code that holds signed material in memory only as long as it takes to submit it, tracks nonces per signing address, decides whether to replace an under-priced transaction, and keeps making progress while an RPC provider degrades mid-flight.

The operating assumption is at-least-once delivery: messages get redelivered, workers get killed, clients retry. Correctness therefore comes from durable state and idempotency keys derived from the business operation, not from hoping each step runs exactly once.

Designed for: no lost instructions, no duplicate settlement, bounded resource use under load.

On chain — the part that must settle deterministically

The token is an ERC-20 implementing ERC-7943, the uRWA interface for real-world assets, with eligibility enforced by the contract on every transfer rather than by an application in front of it. Standards over bespoke: an integrator can discover what a token supports through ERC-165 instead of reading a datasheet.

This is the governed end of the system rather than the immutable one. Tokens are beacon proxies, so the logic can be corrected — but the path to do it is narrow and explicit: upgrade authority lives on the beacon alone, no token role can reach it, and both the admin and upgrade authorities are held by you, not by Tokenistry. Contracts are developed and tested with Foundry — unit, fuzz, invariant and mainnet-fork — and every change is an on-chain event with a signature against it.

Designed for: deterministic settlement, invariant testing, an auditable and customer-held upgrade path.

One instruction, six hand-offs

A forced transfer, an eligibility update and a redemption all take the same path. The owning service changes at each hand-off; the identity of the instruction does not — which is what lets a failure at any step be retried without becoming a second settlement.

  1. 01

    Authorize

    The business operation is validated against domain invariants and caller permissions. An instruction that fails either check is rejected before it can be queued.

    Domain services
  2. 02

    Enqueue

    A durable transaction request is written with an idempotency key derived from the business operation, not from a retry counter. From here on, the instruction survives a restart.

    Transaction Engine
  3. 03

    Sign

    The custody interface requests a signature. Keys stay in your custody workspace, HSM or KMS — the signing backend returns a signature, not key material.

    Custody interface
  4. 04

    Submit

    Nonce assignment, fee strategy, and replacement of stuck transactions — a retry reuses the nonce rather than allocating a second one, so the replacement competes with the original instead of joining it.

    Transaction Engine
  5. 05

    Confirm

    The indexer observes the receipt and normalizes the event, treating confirmation as revocable until the configured finality depth is reached.

    Indexing Engine
  6. 06

    Reconcile

    The owning domain module applies the business meaning — an ownership transfer, a revocation, a redemption — and reconciles its position against observed chain state.

    Investment Ledger

Note where the work is not done: the indexer never decides that a movement was an ownership transfer. It reports that tokens moved. The Investment Ledger decides what that means for ownership. Keeping that boundary sharp is why the two layers can be tested, scaled and upgraded independently — and why a reorg can retract an observation without the ledger having to unwind a business decision it should never have made.

The properties we hold ourselves to

These are the questions a technical due-diligence process tends to arrive at eventually. They are easier to answer when they were design inputs rather than discoveries, so they are stated here as commitments you can test in a proof of concept.

idempotency

A retried instruction settles once, not twice

Idempotency keys are derived from the business operation rather than from a retry counter. Replaying an API call, redelivering a queue message or recovering a crashed worker converges on the same single on-chain effect.

nonce safety

Stuck transactions are replaced, not duplicated

Nonce assignment is serialized per signing address. A replacement reuses the nonce with a higher fee, so it competes with the original rather than queuing behind it — and the address never strands a gap that blocks everything after it.

reorg handling

Confirmation is revocable until finality

Indexed state carries confirmation depth. A reorg rolls back the derived events at the affected depth rather than leaving the ledger asserting an ownership change the chain no longer agrees with.

enforcement

Eligibility is checked on chain, not asserted off it

The token consults the compliance registry inside every transfer, for both sender and recipient. A wallet that is not permitted cannot receive units however the transfer was initiated — including by a Tokenistry service — and a token with no list attached moves nothing at all.

lineage

Every unit of ownership has a traceable origin

FIFO consumption preserves investment lineage across ownership transfers, reallocations and redemptions — so a position can be explained, not merely totaled.

reconciliation

Disagreement is surfaced, not silently resolved

The sum of remaining investments, the internal position and the on-chain balance are compared continuously. A mismatch raises an explicit reconciliation error naming the values that disagree, instead of quietly adjusting one to match the other.

custody isolation

Signing keys stay in your custody backend

Tokenistry services request signatures through the custody interface and receive signatures back; private key material does not enter a Tokenistry process. Keys remain non-exportable in the signing backend you operate, and signing access is constrained by your own IAM, KMS, HSM or custody policy.

observability

Four signals tell you whether the chain-facing path is healthy

Queue depth, submission latency, confirmation lag and indexer head distance are exported in a standard metrics format, alongside health and readiness endpoints and structured logs carrying the operation ID end to end. Degradation is visible as a trend before it becomes a failed settlement.

deployment security

Least privilege is the deployed default

Single-tenant in your cloud account: each service runs with its own database role and its own credentials, secrets come from your secret manager, and outbound access is limited to the RPC and custody endpoints you configure. There is no inbound path for Tokenistry into a production deployment and no phone-home.

upgrades

Rollout and rollback are ordinary deployment operations

Modules ship as pinned image digests with the migrations they require, and migrations are designed to stay backward-compatible within a major version so the previous image still runs against the migrated schema. Contract upgrades are governed separately, and that authority stays with you — no Tokenistry release can alter a deployed token without your action.

What happens when something goes wrong

Chains reorganize, providers rate-limit, workers are rescheduled mid-flight and clients retry. None of these are incidents; they are the normal weather of a chain-facing system, and the design treats them as expected inputs. What follows is what the system does in each case, and how it shows up to whoever is on call.

tokenistry core // failure behavior
What goes wrong What the system does What you see
RPC provider degrades or rate-limits Requests back off and retry. Ingestion resumes from the last checkpointed block, submission holds the queue rather than dropping it, and no state is written from a partial response. Indexer head distance and confirmation lag rise, queue depth grows — all exported metrics, so it alerts as a trend rather than as a data problem after the fact.
The chain reorganizes after an event was indexed Derived events at the affected depth are rolled back and re-derived from the canonical chain. Nothing downstream treats a confirmation below the configured finality depth as final. The reorg is recorded with its affected block range; positions re-converge as the new chain is indexed, without manual repair.
A transaction is under-priced and stuck Replacement on the same nonce at a higher fee, up to a configured ceiling. The nonce is never abandoned, so later transactions from that address cannot be stranded behind a gap. Submission latency for that signing address rises; the replacement is logged against the original request rather than appearing as a new operation.
A worker dies after signing, before the receipt Recovery reads the durable request, checks the chain for a transaction at that nonce, and either resumes tracking it or resubmits. The idempotency key prevents a second economic effect. The operation completes after restart. No duplicate transfer appears in the ledger and no second transaction appears on chain.
A client sends the same instruction twice The duplicate collapses onto the original request through the idempotency key derived from the operation. The second call returns the original operation and its status, rather than creating a second one.
The custody backend is unavailable or declines The request stays durable and unsigned — nothing proceeds without a signature and nothing is discarded. An explicit rejection fails the operation rather than retrying indefinitely. Queue depth rises with the signing stage identified; a declined operation carries the custody backend's reason.
An ineligible wallet is targeted, by any route The transfer reverts inside the contract, because the registry check happens in the transfer path rather than in an application in front of it. The operation fails with the on-chain revert reason attached, before anything settles.
Ledger position and on-chain balance disagree Reconciliation raises an explicit error and stops treating the position as authoritative, instead of adjusting one side to match the other. A reconciliation error naming the token, the holder and the two values that disagree — a decision for a human, deliberately.
A release misbehaves in production Redeploy the previous image digest. Migrations are designed to remain backward-compatible within a major version, so the prior image runs against the migrated schema. Rollback is an operation in your own cluster on your own timeline, not a support ticket to us.

These paths are exercised rather than assumed. The chain-facing services are tested against local chain nodes with the failures injected deliberately — RPC degradation, reorgs, stuck nonces, worker kills mid-submission — and the domain services are tested against a real PostgreSQL instance, because the concurrency semantics are the thing under test. We will walk through this table against your own scenarios in an architecture review.

Runtime, deployment and operations

deployment // your environment

Single-tenant by default. No shared control plane, no phone-home.

Every module ships as a container image with versioned migrations, Helm charts and Terraform modules for the surrounding infrastructure. Deployment targets your existing Kubernetes or container runtime — Tokenistry does not require its own orchestration layer, and a rollout or rollback is the same operation your platform team already performs for everything else they run.

Services expose health and readiness endpoints, structured logs carrying the operation ID end to end, and metrics for queue depth, submission latency, confirmation lag and indexer head distance. Those four signals are the ones that tell an on-call engineer whether the chain-facing path is healthy, and they are exported in a standard format for whatever observability stack you already run.

Each service runs with its own database role and its own credentials, reads secrets from your secret manager, and talks outbound only to the RPC and custody endpoints you configure. There is no Tokenistry-operated control plane in the data path, no inbound path for us into a production deployment, and no runtime dependency on Tokenistry-operated infrastructure — including for licensing.

Distribution. Backend modules are licensed and distributed as container images and compiled binaries, with documented, versioned APIs, OpenAPI specifications and database migrations. The domain layer — ownership lineage, FIFO consumption and the reconciliation semantics above them — is proprietary Tokenistry IP and is not shipped as source. That is what makes it cheaper to license than to rebuild.

The settlement layer is the deliberate exception: smart contract source is available and verifiable on chain, with the admin and upgrade authorities held by you. You should not be asked to trust a contract you cannot read — and because the token, its holders and its eligibility state live on chain, your assets remain reachable independently of the backend that orchestrates them.

Source escrow for the backend is available where operational continuity is a formal requirement. Bring it to the assessment rather than discovering it at contract stage.

FAQ

Can our team extend this, or are we locked in?

You extend through the API, not through our source. The public API is versioned and stable, the schema is documented, and the events you need to react to are published — so your product builds on a documented surface rather than on our internals, and breaking changes to that surface arrive as a new API version rather than as a surprise in a patch release. The backend modules themselves are licensed, not handed over: the ledger and reconciliation logic is the reusable IP that makes buying cheaper than building. Where you need changes inside a module, Tokenistry engineering makes them. Source escrow is available where continuity is a board-level requirement — bring it to the assessment.

Does any of our data reach Tokenistry?

No. The default deployment model is single-tenant inside your cloud account, with your database, your custody workspace and your RPC credentials. Tokenistry is not in the data path and does not operate a control plane your production depends on. See the deployment principle.

Which chains does this run on today?

EVM chains, and only EVM today. Adapters are shared infrastructure rather than products — they exist so the domain modules above them are chain-agnostic, which is what makes another DLT a new adapter rather than a rewrite. Others follow as customer engagements call for them.

How is this tested?

Contracts are covered by unit, fuzz, invariant and mainnet-fork tests in Foundry. The services are tested against a real PostgreSQL instance rather than an in-memory substitute, because the concurrency semantics are the thing under test. The chain-facing services are tested against local chain nodes and simulated failure modes — RPC degradation, reorgs, stuck nonces and worker crashes mid-submission.

What happens if an RPC provider degrades or the chain reorganizes?

Both are expected conditions rather than incidents. Provider degradation slows ingestion and submission instead of corrupting state: progress is checkpointed, requests retry with backoff, and gaps are backfilled once the provider recovers. A reorg rolls back the derived events at the affected depth, because indexed state carries confirmation depth and confirmation stays revocable until finality. In both cases queue depth and confirmation lag rise visibly before anything is at risk. See the failure table.

How do upgrades and rollbacks work?

Backend modules ship as versioned container images carrying the migrations they require, so a rollout is a redeploy of a pinned digest and a rollback is a redeploy of the previous one. Migrations are designed to stay backward-compatible within a major version, so the prior image still runs against the migrated schema. Contract upgrades are governed separately: tokens are beacon proxies, upgrade authority sits on the beacon alone, and that authority is held by you — no Tokenistry release can alter a deployed token.

Related

Blockchain ArchitectureBuild-vs-buy and system design Transaction EngineQueue, nonces and confirmation in detail Investment LedgerFIFO, lineage and reconciliation Indexing EngineNormalized on-chain state Tokenization EngineThe on-chain settlement layer EngineeringCapacity around Tokenistry Core

The stack is the argument

The most useful first conversation is a technical one: what you are planning to build, what you have already committed to, and where the blockchain layer is actually the constraint.

Discuss your architecture