DEV Community: Dmytro Nasyrov

Sportsbook iFrame Integration: Test Reconnects Against the Original Wallet Operation

Dmytro Nasyrov — Thu, 29 Oct 2026 08:40:08 +0000

An iframe can reconnect successfully while its original wallet operation remains unresolved. Test recovery by renewing the session, looking up the original operation and checking the wallet effect. If the first debit committed before its reply disappeared, a fresh session must recover that decision without creating another debit. A reconnect that merely makes the screen responsive can hide the wrong economic result.

This article was prepared with AI-generated research, prose and code. The local test results are recorded below.

Cover: Original technical artwork showing the synthetic reconnect contract.

The example is a small, executable Python model. A fake wallet retains a decision, the reply is deliberately lost and the first session expires. Seven tests distinguish accepted and rejected outcomes from unavailable evidence. They exercise application behavior in one process. They do not run a browser, contact a sportsbook or place a wager.

Give the session and the operation different lifetimes

The session answers whether this caller can currently access the player's operation. The operation identifies the wallet instruction whose result the caller needs. Renewing access changes the session token. It does not change which instruction was previously submitted. Preserve that separation in the reconnect path, even if both identifiers happen to be strings in your adapter.

For this fixture, player alice places ticket-7 using operation-1. The stake is 300 USD minor units against a starting balance of 1000. An accepted operation leaves 700. These are invented values chosen to make duplicate effects visible. They are not a price, customer balance or measurement from a deployed platform.

The immutable intent contains player, operation identifier, ticket, stake and currency. This model treats the ticket as a complete reference to the requested bet. It does not model prices, market suspension or changing bet terms. A production contract would need to define those additional inputs and their versioning before deciding what counts as the same intent.

A temporary session is deliberately absent from that intent. session-1 permits the initial call. Issuing session-2 for the same player makes the first token expire in the fake registry. The original intent still identifies operation-1. Keeping a session token inside the operation key would make access renewal look like authorization for a different wallet change.

Keep the test's meaning narrow: ACCEPTED means the fake wallet accepted this debit. It does not prove that a sportsbook persisted bet acceptance, that settlement completed or that the player's displayed balance is current. Those are separate records and require their own acceptance conditions. A wallet response cannot silently stand in for the rest of the bet lifecycle.

There is one pending intent per frame object in this example. The test calls place() once before recovery and uses fixed positive stakes with one currency. The small runtime does not validate arbitrary user input or prevent another caller from invoking place() again. A real controller needs a defined admission rule for new instructions while an earlier one remains unresolved. The fixture isolates reconnect so that this separate controller problem does not disappear into the demonstration.

Lose the reply after retaining the wallet decision

Fault placement determines what the test can establish. A failure before submission demonstrates that nothing reached the fake wallet. Here, submit() first records its decision and any debit, then raises LostReply. The frame catches that exception and returns UNKNOWN. The caller has lost knowledge of the result while the wallet still holds the result.

The accepted path starts with balance 1000, applies the 300 debit and records one effect. The frame sees no accepted response. Next, the registry issues a replacement session. The original token becomes invalid, so trying to recover through the expired token raises SessionExpired. Renewed access is necessary, but the operation being recovered is unchanged.

In the deliberate defect, BuggyFrame.reconnect() derives a replacement operation from the new session and submits the original ticket again. The wallet sees a different operation identifier with sufficient funds, so it accepts another debit. Its duplicate protection has not malfunctioned: the caller described a new operation to it.

An executed demonstration makes the difference visible. The buggy reconnect returns session-2:replacement, leaves balance 400 and records two effects. The corrected reconnect returns operation-1, leaves balance 700 and records one effect. These are deterministic outputs of the local model. No network latency, throughput improvement or production incident frequency was measured.

The first failing assertion checks the returned operation identifier. A plausible accepted response is insufficient: it must belong to the original intent.

Balance and effect count are also part of the test contract. The separate demonstration reaches those observations on the broken path even though the earlier assertion stops that particular failing test.

Recover a result through a read

Original diagram of the executed synthetic model. Amounts are invented minor-unit values, not production data.

Corrected Frame.reconnect() updates the session used for access and calls wallet.lookup(new_session, self.intent). It does not call submit(). Lookup checks the current session against the intent's player, finds the retained operation and compares the complete intent before returning its stored outcome. Repeating that read leaves the balance and effect journal unchanged.

For an accepted result, the recovery response must identify the same operation and retain the same outcome. This fixture returns accepted:operation-1. It does not invent a new receipt simply because the connection changed. A real adapter should preserve the provider's meaningful result identifiers and distinguish a stored decision from a new attempt to obtain that decision.

The distinction also appears in other API contracts. Stripe describes its API v1 behavior in its idempotent request documentation:

For API v1, Stripe saves the status code and body of the first request made with a given idempotency key after endpoint execution begins.

That is a Stripe-specific replay contract. It illustrates why a retained decision matters, but it does not establish an operator wallet's lookup endpoint, retention period or response semantics. This article's wallet contract is declared in the runnable model. Its recovery operation is a read, while its submission path recognizes repeated operation identifiers and checks their intent.

If the real wallet offers only resubmission with the same key, its documented duplicate-handling contract needs separate verification. Do not mechanically rename that call lookup. Establish which inputs must remain identical, what a concurrent repeat does and whether the original result remains available after session renewal. The correct adapter follows the actual interface rather than assuming another provider's behavior.

Agree on the lookup response before wiring it into the screen. An accepted response should identify the original operation and the decision being recovered. A rejection should carry enough stable meaning for the caller to report that decision without rerunning eligibility. An unresolved response should distinguish unavailable evidence from a known terminal result. The model compresses both unresolved situations to UNKNOWN, while its separate tests retain the reason for each fault.

In a deployed integration, preserve that reason in an internal recovery record even if the player sees one pending message. An operator investigating a failed lookup needs a different next step from an operator investigating a missing retained record. Exposing this distinction internally does not require displaying provider internals or credentials in the user interface.

A retained rejection must survive a changed balance

The rejection test begins with only 100 minor units available for a 300 stake. The fake wallet records REJECTED and applies no debit, then loses the reply. Before reconnect, the test replenishes the balance to 1000. This change is intentional: it makes reevaluation capable of producing a different decision.

Recovery must still return the rejection for operation-1. The corrected frame leaves the replenished balance at 1000 with zero effects. It reads what happened to that operation at its original decision point. It does not ask whether the same ticket might be affordable under today's conditions. A rejection is retained evidence rather than an invitation to rerun a business decision.

The buggy demonstration does the latter. By submitting session-2:replacement, it obtains an accepted outcome and leaves balance 700 after one effect. A test checking only that no duplicate debit occurred would miss this error: the original request was rejected, so there was no first debit to duplicate. The mistake is changing the player's intended operation during recovery.

This is why the acceptance condition needs an outcome identity as well as an effect count. One debit can be wrong when recovery was supposed to report a rejection. In a real product, a later attempt may be valid after the user receives the rejection and explicitly chooses to try again. That is a new instruction with its own authorization and terms.

The model does not decide how a user interface should request that instruction. It supplies a useful boundary for the UI: recovering an unresolved operation and initiating a newly authorized one need distinct paths. A reconnect handler must not take the second path merely because it has regained access to the wallet.

Keep unknown results unresolved

Two tests prevent failed reads from becoming business commands. One disables lookup while preserving the retained decision. The other clears the in-memory journal after the original debit. Both start with a lost accepted reply. Both require UNKNOWN, balance 700 and one effect after reconnect. Neither permits a replacement operation.

These faults represent different evidence problems. An unavailable lookup means the reader cannot obtain a result now. A missing journal entry means this lookup found no retained decision in the model. It does not establish that the debit never happened. The effect list and balance deliberately survive the injected journal loss, exposing that dangerous inference.

Clearing a dictionary is a controlled fault injection, not a storage recovery experiment. There is no disk, replica or crash in this fixture. Its claim is limited to how the frame behaves when the outcome source cannot answer. Durable storage design and the atomic relationship between real ledger effects and retained decisions remain separate work.

Production recovery needs a defined route for this uncertainty. Record the original operation, the evidence available and the owner responsible for resolving it. A later read may establish an accepted or rejected decision. If it cannot, an authorized reconciliation procedure may need another authoritative record. The frame should preserve the unresolved intent rather than manufacture certainty with a fresh identifier.

Do not use the absence of an exception as your oracle. An implementation can swallow lookup failure and return a generic success screen while issuing another debit underneath. Inspect the observable wallet effect and the identity attached to the response. In the missing-journal test, the journal must also remain empty: reconnect must not silently recreate it through submission.

A retention boundary deserves the same care. This example keeps decisions for the life of its in-memory wallet and makes no promise about an elapsed lookup window. Before applying the pattern elsewhere, find out whether operation results can expire while ledger entries remain available. A wallet may need another reference for investigation after that point. Generating a replacement operation cannot restore a pruned response or establish whether an earlier debit exists.

Likewise, a pending decision is different from an absent decision. The fixture records only immediate acceptance or rejection, so it has no asynchronous pending branch. If the real wallet returns pending, define what may transition that operation and what the reconnect read can establish at each stage. Do not add a timer that converts pending into permission to create a second instruction without a documented business rule.

Reconnect evidence	Required result in this model	Additional debit
Retained accepted operation	Original accepted outcome	None
Retained rejected operation	Original rejected outcome	None
Lookup unavailable	UNKNOWN	None
Original journal entry missing	UNKNOWN	None
Session belongs to another player	WrongPlayer	None
Original session expired	SessionExpired	None

Run the same contract against both implementations

The fixture uses Python 3.14.7 and the standard library. Save the two complete files below as recovery.py and test_recovery.py in one directory. The runtime contains the deliberately broken frame and the corrected subclass. The test suite selects the implementation through FRAME_VARIANT, so changing implementations does not change the expected behavior.

Run these commands from that directory:

FRAME_VARIANT=BuggyFrame python3 -m unittest -v test_recovery
FRAME_VARIANT=Frame python3 -m unittest -v test_recovery

The recorded RED run executed seven tests and failed four. The accepted-result, retained-rejection, unavailable-lookup and missing-journal cases failed. Expired-session rejection, wrong-player rejection and conflicting-intent rejection already passed on the broken implementation. Those passing checks matter: the defect survives basic access checks and an operation-key conflict check.

After correction, the same seven tests passed without changing their assertions. The fix adds a reconnect method that performs the original-outcome lookup. This establishes the specified sequential model. Seven tests cannot establish general wallet correctness. The exact test file remained unchanged between the reviewed RED and GREEN runs.

Python's unittest documentation explains the test runner and exception assertions. The dataclasses documentation covers the frozen records and replace() used here. Frozen records make accidental mutation harder in this example. They do not provide persistence, authentication or a transaction boundary around the wallet's dictionaries.

Complete runtime: fake wallet and both reconnect implementations

"""Synthetic in-memory wallet; no network, browser, persistence or real auth."""
from dataclasses import dataclass, replace

UNKNOWN = 'UNKNOWN'


class SessionExpired(Exception):
    pass


class WrongPlayer(Exception):
    pass


class IntentConflict(Exception):
    pass


class LostReply(Exception):
    pass


@dataclass(frozen=True)
class Intent:
    player: str
    operation_id: str
    ticket: str
    stake_minor: int
    currency: str


@dataclass(frozen=True)
class Outcome:
    operation_id: str
    status: str
    response: str


class SessionRegistry:
    def __init__(self):
        self.active = {}
        self.owners = {}
        self.sequence = 0

    def issue(self, player):
        self.sequence += 1
        token = f'session-{self.sequence}'
        self.active[player] = token
        self.owners[token] = player
        return token

    def check(self, token, player):
        owner = self.owners.get(token)
        if owner is None or self.active.get(owner) != token:
            raise SessionExpired(token)
        if owner != player:
            raise WrongPlayer(player)


class Wallet:
    def __init__(self, sessions, balances):
        self.sessions = sessions
        self.balances = dict(balances)
        self.journal = {}
        self.effects = []
        self.lookup_available = True

    def submit(self, session, intent, lose_reply=False):
        self.sessions.check(session, intent.player)
        retained = self.journal.get(intent.operation_id)
        if retained is not None:
            canonical, outcome = retained
            if canonical != intent:
                raise IntentConflict(intent.operation_id)
        else:
            accepted = self.balances[intent.player] >= intent.stake_minor
            status = 'ACCEPTED' if accepted else 'REJECTED'
            outcome = Outcome(intent.operation_id, status,
                              f'{status.lower()}:{intent.operation_id}')
            if accepted:
                self.balances[intent.player] -= intent.stake_minor
                self.effects.append(intent)
            self.journal[intent.operation_id] = (intent, outcome)
        if lose_reply:
            raise LostReply(intent.operation_id)
        return outcome

    def lookup(self, session, intent):
        self.sessions.check(session, intent.player)
        if not self.lookup_available:
            return UNKNOWN
        retained = self.journal.get(intent.operation_id)
        if retained is None:
            return UNKNOWN
        canonical, outcome = retained
        if canonical != intent:
            raise IntentConflict(intent.operation_id)
        return outcome


class BuggyFrame:
    def __init__(self, wallet, session):
        self.wallet, self.session = wallet, session
        self.intent = None

    def place(self, intent, lose_reply=False):
        self.intent = intent
        try:
            return self.wallet.submit(self.session, intent, lose_reply=lose_reply)
        except LostReply:
            return UNKNOWN

    def reconnect(self, new_session):
        self.wallet.sessions.check(new_session, self.intent.player)
        self.session = new_session
        replacement = replace(self.intent, operation_id=f'{new_session}:replacement')
        return self.wallet.submit(new_session, replacement)


class Frame(BuggyFrame):
    def reconnect(self, new_session):
        self.session = new_session
        return self.wallet.lookup(new_session, self.intent)

Complete unchanged test suite

"""Seven observable requirements; identical suite for buggy and fixed frames."""
import os
import unittest
from dataclasses import replace

from recovery import (
    UNKNOWN, BuggyFrame, Intent, IntentConflict, SessionExpired,
    SessionRegistry, Wallet, WrongPlayer,
)


class RecoveryContract(unittest.TestCase):
    def setUp(self):
        import recovery
        self.frame_type = getattr(recovery, os.environ.get('FRAME_VARIANT', 'BuggyFrame'))
        self.sessions = SessionRegistry()
        self.old = self.sessions.issue('alice')
        self.wallet = Wallet(self.sessions, {'alice': 1000, 'bob': 1000})
        self.intent = Intent('alice', 'operation-1', 'ticket-7', 300, 'USD')
        self.frame = self.frame_type(self.wallet, self.old)

    def lose_reply(self):
        self.assertEqual(self.frame.place(self.intent, lose_reply=True), UNKNOWN)
        return self.sessions.issue('alice')

    def test_accepted_lost_reply_recovers_original_outcome_once(self):
        new = self.lose_reply()
        result = self.frame.reconnect(new)
        self.assertEqual(result.operation_id, self.intent.operation_id)
        self.assertEqual(result.status, 'ACCEPTED')
        self.assertEqual(result.response, 'accepted:operation-1')
        self.assertEqual(self.wallet.balances['alice'], 700)
        self.assertEqual(len(self.wallet.effects), 1)
        self.assertEqual(self.frame.reconnect(new), result)
        self.assertEqual(self.wallet.balances['alice'], 700)
        self.assertEqual(len(self.wallet.effects), 1)

    def test_retained_rejection_survives_replenishment(self):
        self.wallet.balances['alice'] = 100
        new = self.lose_reply()
        self.wallet.balances['alice'] = 1000
        result = self.frame.reconnect(new)
        self.assertEqual(result.operation_id, 'operation-1')
        self.assertEqual(result.status, 'REJECTED')
        self.assertEqual(result.response, 'rejected:operation-1')
        self.assertEqual(self.wallet.balances['alice'], 1000)
        self.assertEqual(self.wallet.effects, [])

    def test_unavailable_lookup_remains_unknown(self):
        new = self.lose_reply()
        self.wallet.lookup_available = False
        self.assertEqual(self.frame.reconnect(new), UNKNOWN)
        self.assertEqual(self.wallet.balances['alice'], 700)
        self.assertEqual(len(self.wallet.effects), 1)

    def test_missing_journal_does_not_create_operation(self):
        new = self.lose_reply()
        self.wallet.journal.clear()  # deterministic fault injection, not a real store
        self.assertEqual(self.frame.reconnect(new), UNKNOWN)
        self.assertEqual(self.wallet.balances['alice'], 700)
        self.assertEqual(len(self.wallet.effects), 1)
        self.assertEqual(self.wallet.journal, {})

    def test_wrong_player_recovery_is_denied(self):
        self.lose_reply()
        bob = self.sessions.issue('bob')
        with self.assertRaises(WrongPlayer):
            self.frame.reconnect(bob)
        self.assertEqual(self.wallet.balances, {'alice': 700, 'bob': 1000})
        self.assertEqual(len(self.wallet.effects), 1)

    def test_expired_session_is_denied(self):
        self.lose_reply()
        with self.assertRaises(SessionExpired):
            self.frame.reconnect(self.old)
        self.assertEqual(self.wallet.balances['alice'], 700)
        self.assertEqual(len(self.wallet.effects), 1)

    def test_operation_key_rejects_different_intent(self):
        original = self.wallet.submit(self.old, self.intent)
        with self.assertRaises(IntentConflict):
            self.wallet.submit(self.old, replace(self.intent, stake_minor=400))
        self.assertEqual(self.wallet.lookup(self.old, self.intent), original)
        self.assertEqual(self.wallet.balances['alice'], 700)
        self.assertEqual(len(self.wallet.effects), 1)


if __name__ == '__main__':
    unittest.main(verbosity=2)

Read the conflict test independently of reconnect. It submits the original operation, then attempts the same identifier with a different stake. IntentConflict must preserve the original result and leave one debit. Without this binding, retaining an identifier would not guarantee that the response still described the request the caller intended to recover.

Direct calls make the failure sequence deterministic. No sleeps or probabilistic disconnections are involved. This keeps the suite cheap to run while changing adapter logic and makes the fault point visible in code. HTTP serialization, proxy behavior and provider response parsing still need checks at their actual boundary.

Connect the model to an actual iframe boundary

The Python frame is a stand-in for application recovery logic. It does not create an HTML iframe, exercise cross-origin messaging or inspect browser storage. Move its observable contracts into the real adapter's tests, then add browser coverage for the transport and lifecycle behavior that this local model intentionally excludes.

For a host-to-frame bridge using postMessage, follow MDN's postMessage guidance. Use a specific target origin and verify the received message's origin and expected source. Validate its shape before acting on it. A message arriving from an expected origin does not, by itself, establish authorization for a wallet command.

The adapter also needs an explicit restoration source for the pending intent. A component remount must not erase the only association between the ticket and original operation. Choose storage and access rules appropriate to the actual application. This model retains the intent in the frame object, so it does not test a reload that destroys that object or a restart of the host process.

Map recovery results explicitly rather than testing whether a returned value is truthy. Here, UNKNOWN is a string and accepted or rejected outcomes are records. A generic success branch could accidentally treat all of them alike. The test assertions compare the declared result and its operation identity. When adapting the model to typed responses, keep unresolved evidence as an explicit result that cannot enter the accepted path by default. Any additional error translation should preserve that distinction through the UI adapter.

Exercise stale messages in the browser suite. A reply from an earlier session can arrive after the host has installed a newer bridge. Decide how the adapter associates that reply with the pending operation and which messages are allowed to update the screen. Avoid treating the newest session as the only meaningful identity in every message.

Keep credentials out of the operation record shared with support. The example's session strings are fake registry keys, not production tokens to copy into logs. An evidence export can identify the session transition without distributing live access material. Redaction should preserve the operation join needed for investigation while removing secrets that do not help establish its result.

Make the acceptance record useful to another team

A handoff should let the receiving team reproduce the decision, rather than merely watch the iframe load again. Record the original intent, the lost-reply fault point and the session transition. Show the returned operation identifier beside the balance and effect count. Keep the expected result separate from the output actually observed during the run.

For the accepted example, the expected record is original operation-1, accepted response, balance 700 and one effect. For the rejection example after replenishment, it is the same original identifier, rejected response, balance 1000 and zero effects. Those paired records catch a defect that a single assertion about duplicate debits cannot fully describe.

Include a lookup-unavailable case in the release demonstration. It is often less visually satisfying than a recovered success screen, but it establishes whether the product can remain honest when evidence is unavailable. The acceptance result should show the unresolved state and the retained original intent, alongside proof that recovery applied no additional wallet effect.

When moving this check to a shared test environment, do not rely on a final account balance alone. Another operation can change that balance while recovery is running. Use the wallet's documented operation or ledger references to identify the effect attributable to this intent. The isolated fixture deliberately removes unrelated activity, which is why its simple arithmetic is an adequate oracle inside this model.

Keep a failed run as evidence too. Record the implementation revision and the fault that produced the output, then preserve the same assertions while correcting the recovery path. A passing screenshot from a later run cannot explain why an earlier version created a replacement operation. The useful comparison is the original contract evaluated against both implementations, with their observable outcomes retained.

The wrong-player and expired-session tests establish only the behavior of this fake registry. They do not validate token signatures, revocation propagation, browser isolation or tenant administration. A production security review must examine those mechanisms directly. Passing a synthetic ownership check cannot justify a claim that an embedded betting session is secure.

Concurrency is another explicit limit. The fake wallet executes a decision and journal update sequentially in the same call. It has no lock or database transaction. Two production workers that both observe a missing operation need an atomic admission mechanism at the authoritative boundary. This fixture does not demonstrate that mechanism, and adding threads around its dictionaries would not turn it into a database correctness test. Write the concurrency check against the actual primitive that owns the operation record and debit. Require evidence that both contenders resolve to the declared result without an additional effect, then keep the reconnect test focused on how a renewed caller recovers that result. The two checks answer different questions and should retain separate evidence.

Finally, document the interfaces that were actually exercised. This run covered one sequential process with integer amounts, a single currency and an in-memory outcome journal. It did not cover concurrent wallet requests, real authorization, crash consistency, refunds or sportsbook settlement. Keep those exclusions beside the acceptance record so a passing reconnect rehearsal is not mistaken for a complete integration release.

The next implementation step is concrete: replace the fake wallet lookup with the documented adapter boundary, inject the same lost-reply condition and repeat the accepted, rejected and unknown-result checks. Keep the original operation visible through the session change. For the accepted fixture here, the final evidence remains operation-1, balance 700, one effect.

About the author

Dmytro Nasyrov. Photo supplied by the author.

Written by Dmytro Nasyrov PhD, software architect with 24 years of production experience. Dmytro is the founder of Gambit Stream. He works on production software architecture for FinTech, AI, Web3 and blockchain systems.

Separate Request IDs From Operation IDs in an Integration Retry Test

Dmytro Nasyrov — Wed, 28 Oct 2026 09:00:16 +0000

A lost HTTP response can make an integration send another request for work the server has already committed.

Give that transmission a fresh request ID, but retain the operation ID that identifies the intended business change. A retry test should count the committed effects as well as the responses it receives.

The fixture in this article closes a connection after a SQLite commit and before the HTTP response. Its deliberately broken client creates two reservations. Changing the operation argument passed to the transport function makes the same six tests pass, with one reservation and two separately identifiable attempts.

These are executed results from a local, synthetic inventory example, using Python 3.14.7 and SQLite 3.53.4.

They are not measurements from a customer system. The complete runtime and test module appear below so the claim can be checked without a remote account, API credential or third-party Python package.

This article was prepared with AI-generated research, prose and code. The local test results are recorded below.

Specify what each identifier is allowed to mean

For this fixture, a business operation means one request to reserve a stated quantity of a test SKU for one tenant. The caller supplies its operation ID before the retry loop starts. Each HTTP transmission gets a separate request ID. The receiver returns a reservation ID only after creating or retrieving the business result.

Identifier	Scope in this fixture	Changes on a transport retry?
Operation ID	One reservation intent within a tenant	No
Request ID	One HTTP attempt	Yes
Reservation ID	The stored business result	No, when the operation replays
Tenant	The namespace containing the operation	No

Stripe states in its Request IDs documentation:

Each API request has an associated request identifier.

That is a useful observability role. It does not make a request identifier the correct duplicate-admission key for every receiver. The names on an interface can also differ: AWS calls its caller-supplied idempotency token a client request identifier. Read the promised semantics before deciding whether two fields can share a value.

The client accepts an operation ID and a request-ID generator as different inputs. Tests inject a two-value generator so the expected transmissions are reproducible. Normal calls can use the default UUID generator for each attempt. This arrangement makes identifier ownership visible at the function boundary, rather than hiding it in an exception handler or a transport wrapper.

Do not create the operation ID by hashing the payload alone. Two independent orders can legitimately reserve the same SKU and quantity. They need different operation identities. Conversely, changing a request ID because a connection failed must not change which order the integration is fulfilling. These are separate decisions, and the tests exercise both.

The header names used here are fixture choices. X-Request-ID carries the attempt identifier, while Idempotency-Key carries the operation identifier. X-Test-Tenant supplies a test namespace. None of these headers authenticates a caller. A production receiver must obtain its authorized scope through its actual authentication and authorization boundary.

Put the operation record beside the protected effect

The receiver stores two kinds of rows in one SQLite file. A reservation row is the synthetic business effect. An operation row binds a tenant and operation ID to the canonical request and stored business response. A composite primary key prevents two records from claiming the same identity within that namespace.

Each handler opens its own database connection and explicitly starts BEGIN IMMEDIATE. It looks up the operation while holding the write transaction. An unseen operation creates a reservation and stores its response. A seen operation with matching arguments returns the stored response. Conflicting arguments produce HTTP 409 without creating another reservation.

The important relationship is the transaction containing both writes. If the operation marker could commit while the reservation failed, a later retry might incorrectly report completed work. If the reservation could commit without its marker, a later retry could create another result. A lookup performed before the transaction would not reserve the right to perform the mutation. AWS's idempotent API guidance describes the need to combine recording the token with the related mutations atomically. This fixture applies that principle to one local database. The principle does not turn a database transaction into a transaction with an independent warehouse, payment provider or message consumer.

Request comparison uses JSON with sorted keys and compact separators. This makes object-key order irrelevant for the valid bodies used in the tests.

It is not a general business-equivalence algorithm. Different units, omitted defaults or an API revision can change meaning even when two payloads look similar. Agree those rules separately before adopting this serializer for another interface.

Python's SQLite transaction documentation explains the legacy isolation_level control. Here, isolation_level=None disables implicit transaction opening and the fixture issues its own transaction statements. Each HTTP handler owns and closes its connection. The executed environment is stated above; compatibility with other Python releases was not part of this run.

The reservation is deliberately a row creation, not a complete stock-allocation system. There is no warehouse availability calculation or inventory balance to inspect. This keeps the observable effect small enough to count without deriving it from the returned status. If adapting the fixture to a balance mutation, replace that row-count oracle with the actual invariant for the protected store, and keep the operation record in the same tested transaction. The receiver is a test server accepting the valid request shapes below. It does not implement production input validation, credentials or an internet-facing API contract. Its effect count is a direct database query, so a successful response cannot conceal a second reservation from the test oracle.

Complete runnable file: retry_fixture.py

"""Bounded local HTTP/SQLite experiment. Synthetic data; tenant is NOT authentication."""
import http.client
import json
import socket
import sqlite3
import threading
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from uuid import uuid4


def canonical(value):
    return json.dumps(value, sort_keys=True, separators=(",", ":"))


class Server:
    def __init__(self, path):
        self.path, self.trace, self.drop_once = str(path), [], False
        self.lock = threading.Lock()
        self.stopped = False
        db = self.connect()
        try:
            db.executescript("""
                BEGIN IMMEDIATE;
                CREATE TABLE IF NOT EXISTS reservations (
                    id INTEGER PRIMARY KEY, sku TEXT NOT NULL, quantity INTEGER NOT NULL);
                CREATE TABLE IF NOT EXISTS operations (
                    tenant TEXT NOT NULL, operation_id TEXT NOT NULL,
                    payload TEXT NOT NULL, response TEXT NOT NULL,
                    PRIMARY KEY (tenant, operation_id));
                COMMIT;
            """)
        finally:
            db.close()
        owner = self
        class Handler(BaseHTTPRequestHandler):
            def log_message(self, *args):
                pass

            def do_POST(self):
                body = json.loads(self.rfile.read(int(self.headers["Content-Length"])))
                tenant, operation = self.headers["X-Test-Tenant"], self.headers["Idempotency-Key"]
                request = self.headers["X-Request-ID"]
                payload = canonical(body)
                db = owner.connect()  # Each handler owns its connection.
                try:
                    db.execute("BEGIN IMMEDIATE")
                    previous = db.execute("SELECT payload, response FROM operations WHERE tenant=? AND operation_id=?",
                                          (tenant, operation)).fetchone()
                    status, outcome = 201, "replay"
                    if previous:
                        response = previous[1]
                        if previous[0] != payload:
                            status, outcome = 409, "conflict"
                            response = canonical({"error": "payload_conflict"})
                    else:
                        cursor = db.execute("INSERT INTO reservations(sku, quantity) VALUES (?, ?)",
                                            (body["sku"], body["quantity"]))
                        response = canonical({"reservation_id": cursor.lastrowid, **body})
                        db.execute("INSERT INTO operations VALUES (?, ?, ?, ?)",
                                   (tenant, operation, payload, response))
                        outcome = "created"
                    db.execute("COMMIT")
                except Exception:
                    if db.in_transaction:
                        db.execute("ROLLBACK")
                    raise
                finally:
                    db.close()
                with owner.lock:
                    drop = owner.drop_once and outcome == "created"
                    if drop:
                        owner.drop_once = False
                    owner.trace.append({"request_id": request, "operation_id": operation,
                                        "outcome": outcome, "response_lost": drop})
                if drop:  # Deliberate transport loss strictly AFTER COMMIT.
                    self.close_connection = True
                    self.connection.shutdown(socket.SHUT_RDWR)
                    self.connection.close()
                    return
                encoded = response.encode()
                self.send_response(status)
                self.send_header("Content-Type", "application/json")
                self.send_header("Content-Length", str(len(encoded)))
                self.send_header("X-Request-ID", request)  # Current attempt, never persisted.
                self.end_headers()
                self.wfile.write(encoded)
        self.http = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
        self.port = self.http.server_port
        self.thread = threading.Thread(target=self.http.serve_forever, daemon=True)

    def connect(self):
        # Explicit SQL transactions; None disables sqlite3's implicit BEGIN.
        return sqlite3.connect(self.path, isolation_level=None, timeout=5)

    def start(self):
        self.thread.start()

    def stop(self):
        if not self.stopped:
            self.http.shutdown()
            self.http.server_close()
            self.thread.join(timeout=5)
            self.stopped = True

    def effects(self):
        db = self.connect()
        try:
            return db.execute("SELECT count(*) FROM reservations").fetchone()[0]
        finally:
            db.close()


def attempt(port, tenant, operation_id, request_id, body):
    connection = http.client.HTTPConnection("127.0.0.1", port, timeout=5)
    try:
        connection.request("POST", "/reservations", canonical(body),
                           {"Content-Type": "application/json", "X-Test-Tenant": tenant,
                            "Idempotency-Key": operation_id, "X-Request-ID": request_id})
        response = connection.getresponse()
        return response.status, dict(response.getheaders()), json.loads(response.read())
    finally:
        connection.close()


def reserve(port, tenant, operation_id, body, request_ids=lambda: str(uuid4())):
    for number in range(2):
        request_id = request_ids()
        try:
            return attempt(port, tenant, operation_id, request_id, body)
        except (OSError, http.client.HTTPException):
            if number == 1:
                raise

Lose the response after the commit

A timeout before the receiver performs any work is an easy retry case. The more discriminating case is uncertainty after the work has happened. The test arms a one-shot fault, sends a valid reservation and lets the receiver commit. Only then does the handler shut down the socket before writing a response.

From the caller's side, this appears as a transport failure. It cannot infer from that failure whether a reservation exists. The fixture can inspect both sides because it owns the receiver and database, but a real integration usually has only its local observation until a receiver receipt or reconciliation result resolves the uncertainty.

There is no delay-based race in this fault. The socket close is placed after the explicit COMMIT statement.

An in-memory trace records the request ID, operation ID, result classification and whether the response was deliberately lost. That trace explains the experiment; it is not a durable audit log or a substitute for the database count.

The deliberately broken retry loop passes its fresh request ID in both identity positions:

return attempt(port, tenant, request_id, request_id, body)

The receiver accepts the identities it receives. On the first attempt it sees a new operation key and creates a reservation. On the second attempt it sees another new key and creates another reservation. Adding a uniqueness constraint to the operation table cannot help when the client changes the identity that the constraint protects. The executed demonstration used synthetic SKU TEST-BOLT, quantity 2. Its broken-client trace contains test-attempt-1 followed by test-attempt-2 in both the request and operation columns. The final response reports reservation 2, while the database contains two effects. Checking only that response would miss the duplicate.

The broken and corrected demonstrations start with different fresh database files. They do not repair or delete an extra reservation before counting results. That matters because a compensating cleanup could make the final quantity look right while concealing the duplicate that the client caused. The retained trace labels every value as test data and preserves the created-versus-replayed distinction alongside the stored-effect count.

Keep the fault and the oracle separate when adapting the example. A client-side exception alone does not establish that the server committed. A server log line alone does not establish how many business rows exist. The fixture deliberately observes the post-commit fault and queries the protected store so those two claims can be reviewed independently.

Executed local fixture: the first response is lost after COMMIT; the retry replays reservation 1 under the same operation ID.

Run the same assertions before changing the client

Save the runtime as retry_fixture.py and the test module as test_fixture.py in one directory. The suite starts loopback HTTP servers on ephemeral ports and creates temporary database files. It needs no persistent local service. The test cleanup stops each server and removes its temporary directory.

python3 -m unittest -v test_fixture.py

Before the client correction, the executed suite ran six tests: five passed and one failed.

The failing assertion expected the set of operation identities to contain op-1. Instead it found attempt-1 and attempt-2. That was an identity failure, not a missing dependency, invalid fixture or timing-based setup error.

The failing test first checks the observed attempt sequence, then the operation identity and result classifications. It also requires one stored effect, a successful final status, the second attempt's response header and a business result containing only reservation fields. Those assertions describe behavior at the HTTP and storage boundaries rather than requiring a particular private function call order.

An early assertion failure means later assertions in that test do not run.

The separate buggy-client demonstration therefore supplies the observed two-effect count; the RED test output alone is not presented as proof that every later assertion executed. Preserve this distinction when collecting a failure report for a larger harness.

The other five cases exercise the receiver directly. Their passing results isolate the defect: the supplied key can protect the local effect, but the retry client does not preserve it. A test that replaced the receiver with a mock would need an additional oracle to establish the actual database mutation and replay behavior.

Check which runtime module the test imports before recording RED. A scratch directory with similarly named files can run a corrected module while the reviewer inspects an older copy. Record the loaded runtime file's path and hash with the result, then preserve that exact file. A test name and a passing process exit do not identify the implementation that actually ran.

To reproduce RED from the complete fixed file, work in a scratch copy and replace only the final call inside reserve with the broken call shown above. Keep the receiver transaction, response-loss fault and test module unchanged. Restore the operation argument to reproduce GREEN. A different assertion failure needs investigation before it is treated as evidence of this defect; for example, an import failure has not exercised the HTTP boundary at all.

Freeze the test module while correcting the implementation. Here its SHA-256 remained unchanged between RED and GREEN. That makes the evidence stronger than a passing result produced after quietly weakening the expected operation identity or removing the database assertion.

Move operation identity outside the attempt boundary

The corrected client passes the caller's existing operation ID to every transmission, while obtaining a fresh request ID inside the loop:

-return attempt(port, tenant, request_id, request_id, body)
+return attempt(port, tenant, operation_id, request_id, body)

The operation ID is not regenerated in response to an exception. In the fixed demonstration, both transmissions carry test-operation-1. The first creates a reservation and loses its response. The second replays that stored result. Its response identifies test-attempt-2, and the stored business response still describes reservation 1.

This separation matters on the response path too. If the server cached the first attempt's entire transport envelope, a replay could advertise the wrong request ID. The fixture stores the business response, then adds the current request header when sending it.

The tests check that header independently from the stable reservation result.

The client allows at most two transmissions and retries transport exceptions. It returns ordinary HTTP responses, including the conflict response, without creating a fresh operation. This bounded loop exists to exercise identity preservation. It is not a recommended retry budget, delay schedule or error-classification policy for a production dependency.

The caller must still retain the operation across its own recovery boundary. This fixture receives that identity as an argument; it does not implement a durable job queue or prove that a restarted caller can recover its original intent. Moving ID creation outside one loop is necessary here, but a worker that invents a replacement ID after restarting could reintroduce the same failure elsewhere.

The successful replay deliberately returns HTTP 201, matching this fixture's original creation result. There is no claim that every API must use that status for a replay. If a provider instead returns another documented success status or an asynchronous acknowledgement, test the promised business identity and effect separately from the transport status.

A blanket assertion that every response must be identical can conceal a legitimate current-attempt header or reject a valid provider contract.

Keep resource identity separate from operation identity after success. A reservation can later be amended or released through a different authorized operation. Reusing its original creation key for every future mutation would collapse distinct business actions into one replay record. The field should describe the requested change, not merely whichever resource happens to be affected.

Read the six passing contracts precisely

After the correction and explicit connection cleanup, all six unchanged tests passed. The demonstration recorded one effect for the fixed client and two for the preserved buggy client. These counts describe this fixture and its synthetic inputs. They do not establish throughput, a production error rate or a guarantee across every possible interruption.

Executed case	Observable result	What it distinguishes
Lost response after commit	Two request IDs, one operation ID, one effect	A repeated transmission from a new business action
Changed payload under the same key	HTTP 409, original result retained, one effect	Conflicting intent from a valid replay
Same operation ID in different tenants	Two independent reservation IDs	Scoped identity from accidental global suppression
Different operations with identical payloads	Two reservation IDs	Business intent from payload equality
Receiver restart using the same database	Original result returned, one effect	Persisted operation state from an in-memory cache
Two concurrent callers for one operation	Matching results, one effect, distinct request headers	Atomic admission from a preliminary existence check

The restart case closes the receiver normally and starts another instance over the same file. It does not kill a process during COMMIT or simulate loss of storage power.

The concurrent case submits one pair of callers together; it is not a stress test or proof that every scheduler interleaving was explored.

The conflict test also reverses the order of JSON object keys on a later valid replay. The business result must remain the original one. That check demonstrates the fixture's chosen object-order normalization without claiming that arbitrary strings, numbers or schema versions are semantically interchangeable.

The concurrent assertions inspect both returned results and the stored count. Identical response bodies alone would be insufficient: a defective receiver could create two rows but accidentally return the same one to both callers. Counting rows alone would also be incomplete if one caller received an unrelated reservation. The combined oracle checks that this pair shares the intended result while retaining distinct attempt metadata.

A tenant is not part of every provider's idempotency scope in the same form. The test makes its chosen namespace explicit so reviewers can see what is protected. For another integration, replace it with the receiver's documented account, route and operation scope, derived from an authorized identity rather than a caller's unauthenticated assertion.

Complete runnable file: test_fixture.py

"""Six observable integration contracts; all identifiers and stock are test data."""
import concurrent.futures
import tempfile
import threading
import unittest
from pathlib import Path

from retry_fixture import Server, attempt, reserve

BODY = {"sku": "TEST-BOLT", "quantity": 2}


class Contracts(unittest.TestCase):
    def setUp(self):
        self.temp = tempfile.TemporaryDirectory()
        self.addCleanup(self.temp.cleanup)
        self.db = Path(self.temp.name) / "reservations.sqlite"
        self.server = Server(self.db)
        self.server.start()
        self.addCleanup(lambda: self.server.stop())

    def send(self, operation="op-1", body=None, tenant="test-tenant", request="attempt-1"):
        return attempt(self.server.port, tenant, operation, request, BODY if body is None else body)

    def test_lost_response_retries_one_operation(self):
        self.server.drop_once = True
        status, headers, result = reserve(self.server.port, "test-tenant", "op-1", BODY,
                                         iter(["attempt-1", "attempt-2"]).__next__)
        trace = self.server.trace
        self.assertEqual([t["request_id"] for t in trace], ["attempt-1", "attempt-2"])
        self.assertEqual({t["operation_id"] for t in trace}, {"op-1"})
        self.assertEqual([t["outcome"] for t in trace], ["created", "replay"])
        self.assertEqual(self.server.effects(), 1)
        self.assertEqual(status, 201)
        self.assertEqual(headers["X-Request-ID"], "attempt-2")
        self.assertEqual(set(result), {"reservation_id", "sku", "quantity"})

    def test_payload_conflict_preserves_first_result(self):
        first = self.send()[2]
        status, _, error = self.send(body={"quantity": 3, "sku": "TEST-BOLT"}, request="attempt-2")
        self.assertEqual((status, error), (409, {"error": "payload_conflict"}))
        replay = self.send(body={"quantity": 2, "sku": "TEST-BOLT"}, request="attempt-3")
        self.assertEqual(replay[2], first)
        self.assertEqual(replay[1]["X-Request-ID"], "attempt-3")
        self.assertEqual(self.server.effects(), 1)

    def test_tenants_have_independent_operation_scope(self):
        a = self.send(tenant="test-A")[2]
        b = self.send(tenant="test-B", request="attempt-2")[2]
        self.assertNotEqual(a["reservation_id"], b["reservation_id"])
        self.assertEqual(self.server.effects(), 2)

    def test_distinct_operations_same_payload_create_two_effects(self):
        a = self.send(operation="op-1")[2]
        b = self.send(operation="op-2", request="attempt-2")[2]
        self.assertNotEqual(a["reservation_id"], b["reservation_id"])
        self.assertEqual(self.server.effects(), 2)

    def test_replay_survives_restart(self):
        first = self.send()[2]
        self.server.stop()
        self.server = Server(self.db)
        self.server.start()
        replay = self.send(request="after-restart")
        self.assertEqual((replay[0], replay[2]), (201, first))
        self.assertEqual(replay[1]["X-Request-ID"], "after-restart")
        self.assertEqual(self.server.trace[0]["outcome"], "replay")
        self.assertEqual(self.server.effects(), 1)

    def test_concurrent_identical_operation_has_one_effect(self):
        gate = threading.Barrier(2)
        def caller(i):
            gate.wait(timeout=5)
            return self.send(request=f"concurrent-{i}")
        with concurrent.futures.ThreadPoolExecutor(max_workers=2) as pool:
            results = list(pool.map(caller, range(2)))
        self.assertEqual([r[0] for r in results], [201, 201])
        self.assertEqual(results[0][2], results[1][2])
        self.assertEqual({r[1]["X-Request-ID"] for r in results}, {"concurrent-0", "concurrent-1"})
        self.assertEqual(sorted(t["outcome"] for t in self.server.trace), ["created", "replay"])
        self.assertEqual(self.server.effects(), 1)


if __name__ == "__main__":
    unittest.main()

Adapt the contract at the next system boundary

When the protected effect moves to an independent service, ask what that receiver actually promises. Does it recognize the supplied key, compare changed arguments and retain an authoritative result? A header sent by the client has no deduplication effect if the receiving component ignores it or applies it in a different namespace.

The current Stripe idempotent-request reference distinguishes API v1's saved-response behavior from API v2's retry handling. It also explains that reuse after a v1 key is pruned produces a new request. Those are provider-specific conditions, not settings inherited by this inventory server or every API offering an idempotency key.

An expired replay record leaves an unresolved operation unresolved. Neither reusing the old key nor minting a replacement proves that the earlier action failed. Before retransmitting, obtain the evidence needed under the receiver's recovery contract or hold the operation for reconciliation. A retry counter reaching its limit also does not cancel work already admitted remotely.

Adding an outbox can make a local dispatch intention durable, but the external effect still has its own boundary. A receiver receipt might be lost before local storage. A callback might arrive more than once. Those cases need their own acceptance tests and identity mapping; this reservation fixture does not execute a distributed commit or a webhook workflow.

Observability should preserve that distinction. A trace can connect the attempts, while the operation record identifies what they were trying to achieve. Sampling, log loss or a regenerated trace ID must not silently change duplicate admission. The durable operation store is the authority for this fixture's replay decision, not whichever request happens to remain visible in a tracing interface.

Use opaque identifiers and controlled evidence access in a real service. An idempotency key should not contain a customer's private record or an API credential.

A support operator needs enough context to join the operation to authorized business evidence without exposing sensitive payloads through routine request logs.

Keep an executable acceptance packet

Retain the two runtime versions, unchanged tests and actual command results. Include the interpreter and SQLite versions, the synthetic payload and the precise location of the injected fault. Preserve the demo trace beside the count of rows read directly from the protected database. A screenshot of a green test summary alone leaves those assumptions invisible. Give the reviewer a clean directory and the two files, then have them run the command above. Ask which observed record proves that the first attempt committed and which proves the retry did not create another effect. They should also be able to identify the current response attempt without changing the stored reservation result.

For a real receiver, add its current operation-key contract and the unresolved-outcome procedure before treating the fixture as delivery acceptance. Name any simulated dependency and the later integration gate it still needs. Do not extend a local passing result into a claim about a remote system that the test never called.

A retry is another opportunity to observe or complete the same intent. The integration test earns that conclusion by preserving operation identity through the deliberate response loss and checking the resulting store. Keep the request IDs available for investigation, and keep the business identity stable for the component that decides whether another effect is allowed.

About the author

Dmytro Nasyrov. Photo supplied by the author.

Written by Dmytro Nasyrov PhD, software architect with 24 years of production experience. Dmytro is the founder and CTO of Pharos Production. He works on production software architecture for FinTech, AI, Web3 and blockchain systems.

Regulated Tokenization Engineering in 2026: Identity, Transfer Controls and Auditability

Dmytro Nasyrov — Wed, 21 Oct 2026 08:11:14 +0000

A regulated tokenization system should be able to explain why a particular ownership change was permitted, which authority could override that decision and what evidence survives a later policy change.

A transaction hash answers only part of that question. It does not identify the legal instrument, reproduce an investor assessment or explain the cash leg of a settlement.

The useful engineering unit is a reconstructable decision. Join the instrument definition to an investor record, the wallet binding, the policy evaluated at execution and the resulting ledger changes. Preserve the exceptional route when an administrator intervenes. If those joins disappear, a technically successful transfer can leave operations unable to explain the register it now maintains.

This guide connects identity, transfer enforcement and auditability through one proposed acceptance contract. The source snapshot is October 21, 2026. The walkthrough and acceptance cases below are design exercises, not reported production results or executed tests. The linked implementation articles provide their own narrower artifacts and limitations.

Start with the instrument and the accountable owner

For an EU-facing project, first establish what right the token represents and who owns the classification decision. MiCA is not a universal regulatory wrapper for tokenized assets. Crypto-assets qualifying as financial instruments are excluded from its scope; the applicable securities framework must be considered instead. ESMA's qualification guidelines address that boundary, while MiCA Article 2 supplies the scope rule.

Engineering should receive a versioned requirements record from the issuer and its qualified advisers. That record should distinguish an investor eligibility condition from an operational preference. A transfer limit copied from a slide has no reliable owner, effective date or exception process. Give each implemented rule an identifier that points to the approved requirement and the person responsible for resolving ambiguity.

A useful classification record names the instrument, relevant jurisdictions, rights attached to ownership and the authoritative register. Include the approved distribution and custody model. If the token is a representation of another register, describe which system prevails during a discrepancy. A blockchain balance cannot decide that governance question by itself.

Fragmented ownership between onboarding, contracts and settlement is a software architecture problem. Pharos Production blockchain and FinTech engineering spans those implementation domains; the engagement boundary should name the interfaces and acceptance evidence each team must deliver. Legal classification and authorization remain decisions for the responsible issuer and advisers, rather than conclusions inferred from a token standard.

Translate the requirements into observable behavior before selecting a library. For example, specify whether a restriction prevents receiving, sending or both, what happens to pending instructions and who may authorize recovery. Those distinctions become test expectations. The phrase regulated token has no equivalent precision.

Define the evidence contract before designing the dashboard

A reviewer needs a path from an ownership instruction to the reasons it succeeded or failed. The following matrix is a proposed engineering contract. Its field names are illustrative, and no standard automatically supplies the entire packet.

Boundary	Minimum relationship to preserve	Failure the relationship should expose
Instrument to requirement	Instrument ID, requirement revision, approval owner and effective interval	A rule copied from an obsolete offering
Investor to wallet	Internal subject reference, binding revision and authorized wallet change	A valid wallet signature attributed to the wrong investor
Identity to eligibility	Issuer reference, claim category, validation result and applicable validity rule	A historical approval reused after revocation
Eligibility to execution	Instruction ID, evaluated policy revision and relevant contract configuration	A preview treated as permission for a later state
Execution to ownership	Chain ID, contract address, transaction position, branch identity and ledger effect	An orphaned event still counted as ownership
Exception to authority	Operation type, approving authority, reason reference and affected records	Administrative recovery recorded as an ordinary transfer

Keep the instruction identifier stable across retries, but distinguish every attempted execution. A rejected simulation, a submitted transaction and a finalized ownership entry are separate observations. Collapsing them into a single status overwrites the evidence needed to investigate an uncertain result.

Do not make the token contract store the whole contract of evidence. Some fields belong in a protected case system, some in deployment records and some in chain observations.

The requirement is a reliable join with controlled access. An opaque internal reference is often more useful than copying a sensitive identity document into an event.

Decide how a reviewer will recover historical inputs. A current registry lookup answers a current question. It cannot establish what the system knew when an earlier transfer ran unless the relevant history or reproducible snapshot exists. Define retention and access responsibilities alongside the schema, including what a missing record means for an audit export.

A rejected join is itself a useful acceptance case. Remove one historical policy reference from a rehearsal export and ask the reviewer to complete the reconstruction. The expected result is an explicit incomplete packet with a named missing dependency. The system should not silently substitute today's policy. Test the same case with a reviewer who can see the decision result but cannot open the protected identity dossier. That reviewer should receive an authorized evidence summary or an access limitation, not an unexplained blank. These cases exercise the quality of the evidence interface rather than the correctness of a transfer rule.

Treat identity as a changing relationship

A wallet address identifies an execution endpoint. The investor record identifies the person or entity to which the business attributes rights. A custody arrangement can introduce further relationships between a beneficial owner, an account and the address visible on-chain. Model those relationships explicitly rather than assuming one address always equals one investor.

ERC-3643 separates investor eligibility from offering-wide transfer conditions. Its identity registry associates wallets with identity contracts; required claim topics and trusted issuers contribute to verification. The compliance component addresses rules such as holding limits. That distinction is useful for ownership of failures: an identity problem and an allocation-limit problem require different investigation paths.

For each identity dependency, document who can change it and how the change becomes effective. Replacing a trusted issuer can change eligibility without touching token bytecode. So can changing required claim topics or rebinding a wallet. An audit limited to the token implementation will miss those transitions.

Avoid treating a successful onboarding check as a permanent permission. Your design must say how validity, revocation and source unavailability affect a later instruction. If the chosen implementation does not enforce a required time boundary itself, an operational reminder does not close that gap. Add an enforceable mechanism or narrow the supported workflow.

Retain enough evidence to explain a decision without exposing the underlying dossier publicly. A document hash alone does not establish that the document was accurate, reviewed by an authorized person or lawfully retained. Specify the reference's meaning, access route and retention owner. Use synthetic records for rehearsal, including wallet replacement and an investor whose status changes after an instruction is prepared.

Choose enforcement boundaries, then choose a standard

Identity verification becomes useful only where ownership can actually change. A front-end check cannot prevent a direct call to a transferable token. Begin with an inventory of balance-changing paths and integrations, including issuance, redemption and recovery. Then decide which component has the final authority for each path.

The ERC-3643 versus ERC-1400 comparison examines identity and compliance registries alongside partition and controller concepts. Use it to establish the required semantics. Do not select a standard because its name appears in a procurement specification without checking the implementation and its maintenance boundary.

Next, use the transfer-control architecture comparison to locate the decision: inside the token, in external registries, in signed authorization data, within partitions or through agreement-ledger authorization. Those mechanisms can coexist. A certificate may authorize an instruction while a current registry still decides whether its recipient remains eligible.

Finally, the ERC-3643 implementation walkthrough supplies a concrete country-control module and test fixture. Its stated identity-stub limitations matter. A passing module fixture is evidence about the exercised code and assumptions, not proof that a complete onboarding process or deployed instrument complies with law.

Record the selected boundary in the release packet. Name the exact repository commit, deployed contracts, policy dependencies and custody integration. A reviewer should be able to identify which source answers a disputed behavior. A label such as ERC-1400-compatible is too broad to establish how a particular recovery transaction will behave.

Audit exceptional authority as its own product behavior

Ordinary transfers are only one route through a regulated token's lifecycle. An agent may recover a wallet, force a transfer or freeze holdings. Issuance changes supply. A replacement compliance contract changes future decisions. These operations need explicit business meaning and separate acceptance evidence.

Inspection of T-REX Token.sol at commit f1390127d4270e7f31764c068caf0a1526b852d4 illustrates the distinction. The ordinary transfer path checks pause status, wallet freezes, free balance, recipient verification and compliance. Its agent-only forced-transfer path checks recipient verification and balance but does not use the ordinary pause guard or canTransfer decision. It still invokes the compliance transfer callback. These are source-specific observations, not assumptions about every ERC-3643 deployment.

The operational question is whether that exceptional behavior matches the issuer's approved process. List the gates each privileged operation retains and those it bypasses. Require an authorized reason and a link to the resulting register correction. A successful administrative transaction should never silently inherit the meaning of an ordinary investor instruction.

For a custom token, inheriting an emergency extension is also insufficient evidence that an operator can use it. OpenZeppelin states in its ERC20Pausable documentation:

This contract does not include public pause and unpause functions.

The integrating contract must provide suitably restricted entry points. Rehearse who can pause, who can restore service and what evidence authorizes restoration. A multisig threshold describes a signing requirement; operational independence also depends on who controls the signers and their recovery arrangements.

This is where Pharos Production tokenization and RWA development is relevant to the central problem: the published service scope includes identity registries, compliance modules and transfer restrictions. Turn that scope into an operation-by-operation acceptance matrix. Do not substitute a service description for verification of the delivered authority model.

Authority also has a lifecycle after deployment. Document who can appoint or remove an agent, change an approval threshold and replace a policy dependency. If an operator loses access, identify the recovery route that remains available and the records it produces. A pause procedure that relies on the same unavailable signer as the failed operation has an unresolved dependency. Rehearse signer loss using the intended operational arrangement, without exposing production keys. Record elapsed response time only when measured; a configured delay is not evidence that the team can complete the surrounding approvals within that interval.

Rehearse a revocation while settlement is pending

Consider a proposed exercise, R-17. Investor A instructs a transfer of 40 units to investor B. B is eligible when the instruction is prepared. Before execution, the relevant claim is revoked. The instruction also has a cash-side reservation. These values and identifiers are hypothetical; the sequence below has not been executed for this article.

First, save the preparation observation with its policy and identity references. Keep its result as a preview. Record the validity boundary of any signed authorization. A signature over the instruction proves authorization under its signing scheme; it does not automatically prove current eligibility at the later execution point.

Next, apply the revocation through the intended authority path. Capture the effective chain position or other precisely defined activation boundary. Execute the instruction against the resulting state. Under this exercise's proposed requirement, an ordinary transfer to B must fail and leave token ownership unchanged. If the actual business requirement differs, revise the requirement record and its expected outcome before testing.

Exercise ordering explicitly when the revocation and transfer are submitted close together. Record the accepted execution order instead of assigning meaning from the order in which a browser displayed notifications. If the transfer executes before the revocation becomes effective, its expected outcome may differ from a transfer executed afterward. The requirement owner must approve both cases. Keep separate test identifiers for those orderings and retain their state references. This prevents a race from becoming an ambiguous disagreement between an onboarding timestamp and a chain timestamp. The evidence contract should explain which boundary governs eligibility, how that boundary is observed and what happens when the observation is temporarily unavailable.

The cash reservation now needs its own outcome. Releasing it may be immediate, asynchronous or subject to manual review, depending on the payment integration. Record that outcome separately. A token revert cannot establish that a bank payment or external ledger reservation was reversed.

Exercise variation	Proposed expectation	Evidence to retain
Revocation precedes execution	Ordinary transfer rejected, ownership unchanged	Requirement revision, state reference and execution result
Two instructions compete for available units	Only permitted allocation succeeds	Ordered attempts and before/after ledger reconciliation
Cash release times out	Settlement remains unresolved	Reservation reference, timeout and named recovery owner
Agent performs authorized recovery	Exceptional path identified separately	Authority record, reason and resulting ownership entries
Observed block is replaced	Projection follows the accepted replacement branch	Old/new branch references and rebuilt projection comparison

Do not manufacture a PASS from a screenshot of the final balance. The fixture should assert both the forbidden effect and the required preserved state. It should also prove that a permitted instruction still works. Otherwise, blocking every transfer could satisfy the negative scenario while leaving the instrument unusable.

R-17 is a proposed acceptance exercise. Its decision trail must preserve both the token result and the separate cash outcome.

Build auditability around history and reconciliation

The audit packet must distinguish business intent from chain observation and from the current ownership projection. Each has a different lifecycle. An instruction can remain valid business history even when its transaction disappears from the accepted chain. The ownership projection must follow the accepted branch without erasing the fact that operations observed another result earlier.

Geth's subscription documentation explains that subscriptions concern current events rather than historical replay. It also describes removed logs after a reorganization and repeated logs for the same transaction. An event consumer therefore needs more than a permanent append of every notification it receives.

Preserve chain identity and block ancestry with event position. Make replay idempotent within the chosen branch model. Maintain a recoverable checkpoint and a method to backfill missed observations. Define when a projected balance is provisional and which chain-specific finality policy permits downstream action. Do not invent a universal confirmation count for every network and settlement arrangement.

The indexer recovery exercise demonstrates a narrower synthetic branch-replacement model with a separate snapshot oracle. Use that as an entry point for projection testing. Add the failure modes relevant to your own infrastructure, including process interruption and unavailable historical data, before claiming operational recovery.

Rejected instructions need evidence too. A reverted execution does not leave ordinary success events from that reverted execution as an on-chain rejection journal. Preserve the failed attempt and its observed error through the application or execution tooling, while respecting privacy and retention requirements. Label a local simulation distinctly from an included transaction that reverted.

For exports, include a manifest identifying the time range, branch policy, decoder version and referenced business records. State whether the export is complete. If an identity reference cannot be resolved under the reviewer's access rights, report the gap rather than treating an empty field as proof that no identity decision existed.

A useful reconciliation has two independent views of the same scope. Derive expected ownership from the accepted chain history, then compare it with the application's investor register under the documented custody mapping. A total-supply match alone cannot reveal that units were attributed to the wrong investor. Compare ownership at the granularity needed for the instrument, including restricted categories where applicable. Preserve discrepancies as cases with their own resolution history. An operator's correction should create an attributable adjustment or a documented rebuild, so a later export can distinguish the original observation from the repair.

Invalidate evidence when dependencies change

A release can change eligibility without upgrading the token implementation. Treat changes to claim issuers, required topics, compliance modules and registry bindings as changes to decision behavior. The source tree is only one component of the deployed system.

Keep a deployment manifest that joins implementation identity to configuration and authority. Record the effective boundary for each revision. If two dependencies change in the same operational window, preserve their order. A later review must be able to reconstruct the intermediate state rather than assume the whole window was atomic.

Scope the evidence that a change invalidates. Replacing an event decoder requires projection replay checks. Changing a holding-limit module requires allocation and callback-state checks. Rotating an agent requires permission and operational recovery checks. Altering the custody mapping requires reconciliation with the investor subledger. This gives review a concrete target without pretending every change has the same risk.

An upgrade rehearsal should include historical records and outstanding instructions. Decide whether previously prepared authorizations remain executable, expire or require reapproval. Preserve that decision in the migration runbook. Restoring an old implementation address does not automatically restore registry state, external records or cash movements.

Separate code review from deployment verification. A repository audit may establish what a commit does; operations must still establish that the intended addresses, configuration and authority are active. Keep the audit's scope and unresolved findings beside the deployment manifest so a report for one configuration cannot silently represent another.

Define a practical exit condition for a failed migration rehearsal. If the old software cannot interpret records already created by the new policy, returning traffic to it is insufficient. Identify the point after which a forward repair or explicit data conversion is required. The release owner should know that boundary before authorizing the change. Tie the recovery choice to a retained snapshot and a tested procedure with its own evidence. This is especially relevant when the token code remains unchanged but a new registry relationship changes the meaning of records consumed by settlement or reporting.

Before accepting an archive, attempt an unauthorized substitution in a synthetic packet. Replace a policy file while leaving its friendly filename unchanged, or point an evidence reference at a different revision. The reviewer should detect the substitution through the agreed integrity mechanism. Hashes help identify byte changes, but the packet also needs an authenticated connection to the release or approval it represents. Define who signs or otherwise attests that relationship and how the reviewer verifies it. This proposed negative check tests evidence integrity; it does not establish the truth of every underlying business assertion.

Make the handover answer a disputed transfer

Ask a delivery team to reconstruct one ordinary success, one denied instruction and one authorized exception from the proposed packet. Start with an instruction reference rather than a dashboard chosen by the team. Follow the joins until an independent reviewer can identify the evaluated policy and reconcile the resulting register.

Agree the boundaries of that review in advance. State which external identity service, payment system and custody records are included. If a dependency is simulated, mark it clearly and name the later integration gate. The goal is a usable acceptance process with visible limits, rather than a larger collection of reports whose coverage cannot be compared.

Operations should leave the handover with named owners for stale identity inputs, uncertain settlement and projection recovery. Give each owner a runbook entry and evidence they can retrieve with their actual access. A technically complete archive that only a departed developer can decode will not resolve an investor dispute.

Regulated tokenization engineering becomes reviewable when those responsibilities connect. A standard defines useful interfaces. Executable behavior comes from the implementation. Operations determine how identity changes, exceptional authority and settlement failures are handled. Acceptance should demonstrate the joins with the deployed configuration and preserve enough history to explain them later.

About the author

Dmytro Nasyrov. Photo supplied by the author.

Top 5 Token Transfer-Control Architectures for Regulated Assets Compared

Dmytro Nasyrov — Wed, 14 Oct 2026 08:40:15 +0000

Choose a token transfer-control architecture by locating the authority that can approve a change of ownership at execution time. An embedded rule, an identity registry, a signed certificate, a partition policy and an agreement ledger can all restrict movement. They place the decision in different systems, however, and they respond differently when permission changes while a transfer is pending.

For a regulated instrument, the useful comparison starts with a rejection condition: can the design enforce the actual ownership rule across every supported movement path? Wallet compatibility and operating cost matter after that condition is satisfied. A successful ordinary transfer says little about delegated movement, recovery or an upgrade that changes the policy dependency.

The five models below are an editorial selection, with sources checked on October 14, 2026. Section numbers identify the designs; they do not represent benchmark scores. The examples compare enforcement mechanisms rather than vendors. A production system may combine several models, but each entry describes a complete decision boundary. Legal counsel and the instrument documentation determine the ownership rules that engineering must implement.

Compare the decision boundary first

Use one requirement across the comparison: an eligible holder may move an eligible quantity to an eligible recipient, subject to the instrument's restrictions. Record which system supplies each fact and which action changes it. A controller's exceptional authority belongs in a separate path with its own conditions.

Architecture	Scenario fit	Trust boundary	Principal failure	Evidence to require	Operating constraint	Reject when
Embedded token rules	A small, stable rule set for one instrument	Token code and local policy administrators	An overlooked balance-update path bypasses the check	Entry-path map and negative tests	Each policy change affects token state or code	Several instruments require independently governed shared policy
External identity and compliance registries	Several identities or rules need reusable state	Registry issuers, module administrators and dependency pointers	A trusted dependency changes without the intended review	Registry topology and mutation history	Availability and governance span multiple contracts	The issuer cannot operate or audit those dependencies
Signed transfer certificates	Each proposed transaction needs contextual approval	Off-chain decision service, signer and verifier	A valid old authorization survives a policy change	Signed payload, replay rules and revocation trace	Every required approval depends on certificate issuance	The service cannot meet the required interruption behavior
Partition-scoped policy	One holding contains quantities with different restrictions	Partition accounting and policy for movement between classes	Conversion turns restricted units into transferable units	Conservation and conversion invariants	Custody and settlement adapters must understand partitions	Integrations can see only aggregate ERC-20 balances
Agreement-ledger authorization	Ownership movement requires several parties' authorized actions	Contract signatories, choice controllers and business assertions	Properly authorized parties execute an inadequately constrained choice	Contract lifecycle and authorization trace	Participants must support the ledger and workflow	Deployment must remain an ordinary EVM token integration

1. Pharos Production: Token Transfer-Control Architecture with Embedded Rules

An embedded gate keeps the relevant policy state beside the token's balance logic. A design might store approved recipients, frozen accounts or instrument-specific holding limits locally. The transfer path evaluates that state before it changes balances. This is a reasonable baseline when the rule set is limited and one issuer controls its lifecycle.

The central problem is translating an instrument rule into an enforceable state transition. Blockchain engineering at Pharos Production includes smart-contract design and integration work; the service is relevant to identifying that transition and its dependencies. This baseline describes a generic architecture, without claiming that the company owns a special token standard or that this article demonstrates a delivered client implementation.

OpenZeppelin's ERC-20 documentation identifies _update as the customization point for balance updates in Contracts 5.x. It covers transfers, minting and burning. That gives a designer a place to implement local conditions, but inheriting a token base does not supply an instrument's complete transfer policy. Conditions appropriate for a transfer between holders may be wrong for issuance or redemption.

The strongest reason to select this architecture is the short enforcement path. A reviewer can follow local state from the administrative write to the balance update without resolving a network of policy contracts. The same simplicity becomes a constraint if several instruments need one independently governed eligibility service. Copying local lists across them introduces synchronization work and creates multiple opportunities for stale decisions.

Request an entry-path map before judging the implementation. Include direct and allowance-based transfers, mint and burn operations, recovery and every privileged balance adjustment. For each path, identify whether the local gate executes and what exception permits it to proceed. A diagram that ends at the public transfer method is incomplete.

A useful negative case removes the recipient's permission before the transaction executes. The balance must remain unchanged if the instrument requires current eligibility. Then repeat the case through delegated transfer. An allowance proves spending authority; it should not silently substitute for the recipient's eligibility. Keep the denied result and the relevant policy state together in the release evidence.

2. External Identity and Compliance Registries

This architecture moves eligibility and transfer policy into dependencies that the token consults. The token remains the balance authority, while a registry can connect a wallet to an identity and another contract can evaluate rules about the proposed movement. The model suits systems that need reusable claims or separately maintained policy modules.

ERC-3643 describes identity registries, trusted issuers and claim topics alongside compliance checks. Its structure makes the provenance of eligibility an explicit engineering concern. A wallet address is one input to that structure; it is not by itself evidence that the represented investor satisfies the instrument's requirements.

The implementation boundary matters as much as the specification. In the pinned T-REX token source, ordinary movement checks recipient verification and compliance. Administrative paths have different conditions. Review the exact release and configuration rather than assuming that every function follows the ordinary transfer predicate.

Operationally, the policy can change through more than a token upgrade. An issuer's claim can disappear, a trusted issuer can be removed or a module can be replaced. A dependency pointer can redirect the token to a different decision-maker. Those are material policy changes even when the token bytecode and its public interface remain identical.

Ask for a topology that names each dependency, its administrator and the facts it supplies. Beside the topology, retain the events or other records that reconstruct changes to claims and configuration. A current registry response explains today's decision; it does not automatically explain a transfer that occurred under last month's configuration.

Choose this model when shared policy ownership is an advantage and the organization can operate that additional state. Reject it when no team accepts responsibility for claim refresh, dependency monitoring or permission recovery. Outsourcing the check into a contract changes the location of the work; it does not remove the work.

The decisive acceptance case changes a trusted dependency after a successful preflight. The transaction should follow the documented execution-time rule, and its evidence should identify the dependency version actually consulted. The user interface must be able to explain why a previously valid proposal now fails without treating the failure as an unexplained wallet error.

3. Signed Transfer Certificates

A certificate architecture approves a specific proposed transaction off chain and verifies the approval during execution. It can use information that is inappropriate to place on a public ledger, including contextual review results. The token or its extension checks that the submitted authorization came from an accepted signer and applies to the intended movement.

The Consensys UniversalToken repository describes off-chain certificates carrying signed transaction parameters. It also describes on-chain validated-investor lists as another control mechanism. This is an example of why a standard name does not uniquely identify the architecture. The same token family can support different policy boundaries or a hybrid configuration.

The important distinction is between a cryptographically valid approval and an approval that still satisfies current policy. A certificate issued before a recipient is disqualified may remain mathematically valid afterward. Whether it should execute is an instrument and system-design decision. The verifier needs an explicit mechanism for whatever freshness rule the issuer requires.

Require evidence for the signed payload. It should bind the authorization to the relevant asset contract and deployment domain, the parties, quantity and action. Review how the implementation limits reuse and what happens after signer rotation. These are acceptance requirements for the chosen implementation, not an assertion that every certificate-based token supplies them.

Expiry alone may not meet an immediate revocation requirement. A short validity window still leaves a window. A live on-chain revocation check, a policy generation number or another documented invalidation mechanism can close that gap, but each adds state and operational obligations. Decide what outstanding certificates mean when the signer is removed or the policy generation changes.

This model can support detailed transaction review without publishing the underlying personal information. It also places issuance service availability on the path to transfer. If the service cannot issue a certificate during an outage, the expected behavior may be rejection, queuing or an independently governed exception. A silent fallback to an unrestricted transfer defeats the premise.

Before selection, replay a captured authorization against altered transaction parameters and after its permitted use. Also prepare a certificate, revoke the recipient and attempt execution. Record which fact invalidates the approval. If the system cannot name that fact, it cannot substantiate a claim that transfers always reflect current eligibility.

4. Partition-Scoped Transfer Policy

Partitions distinguish quantities within a holder's balance. One investor might hold transferable units alongside units subject to a lock or another restriction. A partition-aware transfer identifies the category being spent, rather than leaving the system to infer it from an aggregate balance.

ERC-1410's partition model provides interfaces for those categories and their movement. Partitions supply accounting structure. The eligibility predicate still needs implementation through token logic, extensions or another control. Labelling a balance as restricted does not make it restricted unless the movement paths enforce the label's meaning.

Consider an illustrative holding of 150 units: 100 transferable and 50 locked. A request to move 120 cannot be approved merely because the aggregate balance is sufficient. The design must reject it, split it under an explicitly allowed rule or identify a permitted conversion. Otherwise the partition system preserves labels while losing the ownership constraint those labels were meant to express.

The dangerous edge is movement between categories. An administrator or holder might be able to convert a locked partition into a transferable one. That conversion needs its own policy and evidence. A transfer check applied only after conversion can appear correct while the conversion function has already erased the restriction.

The pinned UniversalToken implementation shows partition-specific balance movement and extension handling. Its accounting illustrates the integration burden: downstream systems need to preserve the meaning of the partition selected for a movement, not just the total quantity appearing in an ERC-20-compatible view.

Select this architecture when different portions of a holding have materially different rights or restrictions. Reject it when custody and settlement adapters cannot identify those portions. A sophisticated contract behind an adapter that flattens every balance can produce a misleading available-to-transfer amount and incorrect settlement instructions.

The acceptance evidence should show conservation across partitions, rejection from the wrong category and policy enforcement on category changes. Corporate actions also need attention: replacement units must retain the intended restriction state. A migration that recreates only aggregate balances can discard the very information that justified choosing partitions.

5. Agreement-Ledger Authorization

An agreement-ledger design represents ownership and the permitted actions over it as contracts between identified parties. A transfer becomes an authorized contract lifecycle transition. This changes the platform assumptions, but it is a genuine alternative when the business requirement is controlled ownership movement rather than mandatory use of an ERC-20 wallet interface.

Digital Asset's Daml authorization pattern distinguishes party authority from an issuer's accreditation check. Its example uses an authorization contract for the new owner and checks that authorization during acceptance of a transfer proposal. Built-in permission to exercise a choice does not replace the business condition inside that choice.

This distinction is valuable in a workflow involving an issuer and two counterparties. The owner can propose a movement, while the recipient participates in acceptance and the issuer's authorization constrains who may hold the asset. Review the complete action chain. The set of parties who can submit a command is only one part of the question; the resulting ownership contract must also satisfy the business rule.

For instrument rules that span counterparties and settlement operations, the relevant engineering work includes the legal wrapper and transfer-agent process. Pharos Production's tokenization and RWA development service describes that wider scope. A technical selection record should connect those obligations to the ledger transition and its evidence without implying that a platform choice establishes legal compliance.

The operating constraint is substantial. Participants need compatible ledger access, party administration and integrations for their contract workflow. An existing EVM custody adapter cannot be assumed to support it. A bridge back to a public-chain token creates another boundary: its mint or release conditions must preserve the original ownership restrictions.

Choose this model when explicit multi-party authorization and controlled workflow are central to the instrument. Reject it when deployment must stay inside an existing EVM-only ecosystem and that constraint cannot change. Cross-platform portability is a project in its own right, with its own authority and reconciliation requirements.

An acceptance case archives or otherwise invalidates the required authorization before the recipient accepts a pending proposal. The application should demonstrate the intended rejection and unchanged ownership. Separately test an authorized party attempting a choice with the wrong asset or issuer context. Proper command authorization must not turn a mismatched business object into a valid transfer.

Walk One Revocation Through All Five Designs

Illustrative acceptance scenario; no executed test result is shown.

Use the same hypothetical timeline in an architecture review. At preparation, Alice holds sufficient transferable units and Bob is eligible. A proposal to move 40 units is prepared. Before execution, the issuer removes Bob's eligibility. The required result is that the ordinary movement does not complete. This is a proposed acceptance scenario, not a report of tests executed for this article.

Design	State that must decide execution	Evidence that distinguishes correct rejection
Embedded gate	Updated local eligibility state	Gate reached through the selected entry point; balances unchanged
External registry gate	Effective identity and compliance dependencies	Consulted dependency addresses and policy state at execution
Certificate gate	Authorization validity plus the chosen freshness mechanism	Old certificate rejected for a documented invalidation reason
Partition gate	Transferable partition and recipient rule	Sufficient unrestricted quantity cannot override recipient ineligibility
Agreement ledger	Required authorization contract and acceptance conditions	Pending proposal cannot create the new ownership state

The table deliberately requires more than an error message. A rejection should have an explainable cause, and a failed movement should not leave partial ownership changes. For the certificate design, current eligibility is an additional requirement to prove. For partitions, eligibility and quantity category are separate predicates. Combining them in a green interface badge conceals which one actually failed.

Repeat the timeline with a prepared settlement instruction and a cash leg. A token transfer rejection may leave an off-chain payment process running. The architecture record must say whether settlement is atomic, reserved, compensatable or subject to manual resolution. Transfer controls protect the asset movement they govern; they do not automatically govern the neighboring payment system.

Retain the proposal identifier across the issuer's eligibility record, transaction attempt and settlement state. That connection lets an operator explain a denied movement without reconstructing unrelated logs by hand. If an indexer temporarily falls behind, its cached permission state should not override the authoritative execution result. The user-facing status can remain pending until the system has evidence for a final outcome.

Give Emergency Paths Their Own Policy

A pause capability and a usable emergency process are different deliverables. OpenZeppelin makes one concrete implementation boundary explicit:

This contract does not include public pause and unpause functions.

Source: OpenZeppelin, ERC20Pausable documentation.

The documentation requires the inheriting implementation to expose those operations with appropriate access control. The architecture review must then determine who holds that authority and how an operator proves that the action was legitimate. A library feature is only part of the response process.

Treat recovery, forced movement and policy replacement as distinct paths. The pinned T-REX implementation's forcedTransfer uses agent authority and recipient verification while bypassing the ordinary canTransfer check. That source-specific behavior is precisely why an ordinary transfer test cannot validate every administrative movement. The bypass may serve an intended purpose, but its permitted scope needs explicit review.

For each exception, retain the initiating role, allowed action and resulting state change. Identify which ordinary conditions remain enforced. Then test the exception under pause and after role revocation according to the release's intended behavior. Do not assume that a pause stops every administrative function or that a multisignature alone defines a correct exception policy.

An upgrade can alter any of these relationships. Review storage and state migration alongside policy semantics: old identities, outstanding certificates, partition labels and pending proposals may remain relevant after code changes. The acceptance record should identify what happens to each of them, especially where a new release recognizes a different authority.

Make the Selection Reviewable

Write the selection as a short contract between the instrument team and the engineering team. Name the ownership record, the ordinary movement predicate and the permitted exceptions. State the integrations that must remain compatible. Record the selected architecture and the alternatives rejected by a specific operating constraint.

The release packet should include the exact source commit and deployed code identity, configuration and administrators, policy dependencies and the evidence for each proposed acceptance case. For a signed design, add the signer lifecycle and payload definition. For partitions, add conversion and conservation evidence. For the agreement-ledger design, include the contract packages and the parties' authorization chain.

Estimate operating work against the same expected workload. Count permission updates, certificates that must be issued and rejected proposals requiring investigation. Include the administrative response when one dependency fails. A local gate may minimize components while multiplying policy updates across instruments. A shared registry may reduce duplication while adding shared governance. Neither observation is a gas or throughput measurement; it identifies work that the project must cost with its own traffic and staffing assumptions.

Acceptance should also cover a recovery handover. Give a replacement operator the recorded configuration and ask them to explain one successful movement and one rejection without relying on the original developer. Missing policy versions or disconnected approval records will become visible immediately. Preserve the unresolved questions as release blockers rather than filling the gaps with a general statement that the token is compliant.

Keep source inspection separate from execution. The references here establish mechanisms and implementation boundaries; the hypothetical cases describe what a project should demonstrate. They do not certify any repository, deployment or instrument. The UniversalToken repository is archived, so its pinned implementation is an architectural reference rather than evidence of a maintained production release.

Choose the smallest design that preserves the instrument's required rejection behavior through normal movement, exception paths and change. If the architecture cannot explain the prepared transfer after eligibility is revoked, postpone selection and resolve that missing contract. That unresolved case is more useful than a feature checklist whose rows all say that compliance is supported.

About the author

Dmytro Nasyrov. Photo supplied by the author.

ERC-3643 vs ERC-1400: How to Choose a Standard for Tokenized Instruments

Dmytro Nasyrov — Wed, 07 Oct 2026 06:16:16 +0000

Choose ERC-3643 when the central requirement is that a token can move only to an eligible investor represented through an on-chain identity system. Evaluate an ERC-1400 implementation when the instrument needs explicit subdivisions of a holder's balance, partition-specific operations or the interfaces in that standards family. If the product needs both, neither label finishes the architecture: select an implementation and prove how its identity and partition policies interact.

The difficult question is what a particular transaction must preserve. A wallet can hold enough tokens and still be unable to transfer the requested amount. A registered investor can lose eligibility after a transfer preview. A transfer agent can have authority to correct ownership while ordinary transfers remain paused. These are different conditions, with different owners and failure paths. In the example below, 150 units cannot fund a 120-unit transfer when only 100 are transferable.

For blockchain engineering at Pharos Production, the useful starting point is a behavior specification connecting an instrument requirement to an observable transaction outcome. Ask for that artifact before comparing feature counts. An issuer choosing a token standard needs to know which behavior is supplied, which depends on configuration and which needs new engineering.

This comparison uses the published ERC-3643 specification, the original ERC-1400 family documents and two pinned public implementations. Sources were checked on October 7, 2026. It makes architecture recommendations from those interfaces and source paths; it does not report a production deployment or a comparative security audit.

Start with the instrument, not the token number

Write the instrument's rights in language a fund administrator and an engineer can both inspect. Does every unit carry the same economic rights? Can two units in the same wallet have different transfer restrictions? Who decides that a subscription is complete, that a holding period has expired or that ownership needs correction?

Consider a fund share with one class of economic rights. Investors must be approved before receiving it. Transfers have a concentration limit. Lost-key recovery is an operational requirement. Here, investor identity and transfer controls are the primary engineering problem. ERC-3643 is a natural candidate because its interfaces directly describe the identity registries and administrative operations that this workflow needs.

Now consider an instrument whose units are divided into issuance lots with different release conditions. A holder can own both transferable and restricted units. An intermediary must specify which lot it is moving and retain that information in its records. Partition-aware operations deserve a place in the evaluation. Whether those partitions represent lots, lockups or something else is an issuer-approved design decision.

Different economic rights need further scrutiny. Separate share classes might require separate contracts, distinct accounting or a carefully specified partition model. The ability to assign a partition key does not establish the legal meaning of that key. Nor does a single ERC-20 balance demonstrate that all the units it aggregates are interchangeable for settlement.

The selection worksheet should therefore contain four fields: the unit's rights, the state that restricts movement, the actor authorized to change that state and the evidence retained after a change. A standard is useful when its interfaces fit these requirements without hiding a material distinction in an application database.

Compare a final specification with a standards family

ERC-3643 is marked Final in the Ethereum Improvement Proposals repository. It defines token, identity registry, identity storage, compliance, trusted issuer registry and claim topic registry interfaces. It requires ERC-20 compatibility and an on-chain identity system. It also describes recovery, freezes, pause, minting, burning and agent authority.

The original ERC-1400 document describes an umbrella of related interfaces. Its retained front matter says Draft. One of its authors is Fabian Vogelsteller, also associated with the development of Ethereum token interfaces. The authors describe its scope in one short sentence:

Represents a library of standards for security tokens on Ethereum.

That sentence matters in procurement. ERC-1400 on a slide does not identify the exact interface set, restriction system or administrative behavior delivered by a vendor. Ask which members of the family are implemented and which extensions are proprietary.

Family document	Engineering job	What still needs a design decision
ERC-1410	Partition balances and partition operations	Meaning of a partition and permitted transitions
ERC-1594	Transfer validity queries, attached data, issuance and redemption	Policy source, authorization data and failure handling
ERC-1643	Document references and updates	Document governance, storage and investor access
ERC-1644	Declared controller operations	Controller authorization and correction procedure

A Final status is a specification maturity signal. It is not evidence that a deployed configuration has been audited, that an upgrade is safe or that a venue supports the token. Conversely, a draft-family implementation may have useful production-oriented features. Evaluate the repository, deployment and operating model separately from the status of the document.

ERC-3643 makes investor eligibility an explicit dependency

ERC-3643 connects a receiving wallet to an identity record and checks the required claims against trusted issuers. The claim topics define what must be established; the trusted issuer registry defines whose attestations are accepted. The token's compliance component handles offering-level rules, such as concentration or holder-count restrictions, separately from identity verification.

This separation helps diagnose a rejected transfer. The recipient might be unregistered, lack a required claim or fail a token-level rule despite having a valid identity. A frozen wallet or insufficient unfrozen balance is another reason to reject movement. A front end that collapses every case into an eligibility error sends the operator to the wrong system.

The specification's ordinary transfer conditions include recipient verification, wallet freeze checks, free balance, pause state and the compliance result. Do not expand that into a promise that every entry point checks every condition. Administrative operations have different semantics, and the selected implementation must be inspected individually.

The eligibility owner needs a response procedure as well as contract permissions. If an onboarding provider stops serving an attestation, identify who investigates, who may replace the evidence and how pending instructions are handled. A registry administrator should not make an undocumented exception simply to clear a settlement queue. Keep the rejected instruction linked to its policy evidence so that a subsequent approved retry can be explained.

Identity freshness also needs an operating policy. Removing an accepted issuer, revoking an attestation or changing a claim requirement can affect future receipts. It does not necessarily remove an existing balance. Decide whether an investor who becomes ineligible may continue holding, redeem, transfer out through a restricted route or require an administrative action. Then encode and test the approved behavior.

A wallet-to-identity relationship also needs a custody model. For an omnibus custodian, the contract may identify the custodian wallet while the beneficial-owner allocation remains in its ledger. That is a different visibility boundary from individually registered investor wallets. Neither model becomes correct merely because a registry call returns true.

Avoid putting sensitive onboarding documents into public transaction data to simplify integration. The token system needs verifiable eligibility evidence and controlled links to the off-chain record. The location of personal information, access permissions and correction process should be explicit parts of the identity design.

ERC-1400 partitions expose which balance is moving

ERC-1410 describes balances grouped under partition keys while retaining aggregate owner balances and supply information. Operations can address a particular partition. This gives an integration a way to distinguish parts of a holding that would disappear into a single aggregate balance.

A partition is a label and associated balance in the interface. Its restrictions come from the contract's policy. Naming a partition LOCKED does not itself create a time lock. A partition named AVAILABLE does not prove that the recipient is eligible. The implementation must enforce the corresponding conditions through its transfer path and extensions.

The pinned Consensys UniversalToken implementation exposes partition transfers and operator transfers. Its transfer path invokes extensions and maintains partition balances. Its README discusses both signed transfer certificates and on-chain lists of validated investors. These are concrete policy mechanisms in that implementation, not proof that every ERC-1400 token uses the same identity architecture.

A certificate-based design can attach authorization to an intended transaction. It introduces an issuer or policy service that must remain available and issue the correct authorization. A list-based design moves an eligibility lookup on-chain but needs transactions to keep that state current. An engineering choice between them must account for revocation latency, replay protection and the integration's ability to supply the required data.

Partition behavior also reaches the user interface. A wallet displaying 150 units should distinguish transferable units from restricted units when that difference matters. Custody reports need the partition balances, and a settlement instruction needs an unambiguous source partition. Otherwise the application promises liquidity using an aggregate number that the transfer path cannot spend.

Use disqualifiers before assigning scores

A weighted feature score can hide a missing requirement. A candidate with a polished dashboard might score well while lacking the operation an approved instrument needs. Set the rejection conditions first, then compare engineering and operational costs among the remaining candidates.

Requirement	ERC-3643 candidate	ERC-1400 candidate	Reject the candidate when
Reusable investor eligibility	Explicit identity and claim registries	Inspect the chosen list, certificate or identity extension	Eligibility updates cannot be explained or tested
Different restrictions inside one holding	Additional lot or state model may be needed	Evaluate partition-aware operations	Required distinctions exist only in a display label
Explain a refused transfer	Combine identity, compliance and token-state diagnostics	Inspect validity queries and implementation reason codes	Preview contradicts execution without a diagnosable change
Administrative correction	Agent and recovery operations are specified	Inspect controller and operator capabilities	Authority or bypass behavior is undocumented
Documents tied to an instrument	Define the document integration separately	Evaluate the ERC-1643 interface and its implementation	Updated terms cannot be retrieved and reconciled
Existing custody or venue integration	Prove restricted ERC-20 operations work	Prove aggregate and partition operations work	Required calls or events are unsupported
Upgrades and policy changes	Inspect registries, modules and deployment authority	Inspect extensions, partition semantics and deployment authority	A change can silently reinterpret outstanding holdings

Pharos Production's tokenization and RWA development process describes working alongside legal counsel to map asset ownership rights to token mechanics. That mapping addresses the central selection problem: engineering needs approved rights and restrictions before choosing a contract model. Ask for a requirement-to-operation matrix as the handoff, with legal assumptions distinguished from demonstrated software behavior.

Walk one holding through both models

Use an illustrative holding of 150 units: 100 currently transferable and 50 restricted. The holder requests a transfer of 120 units to an eligible recipient. Assume the token is not paused and both wallets satisfy the applicable conditions. These numbers are a design example, not measurements from a deployed system.

An ERC-3643 design could represent the restriction as 50 partially frozen tokens. The ordinary free balance would be 100, so the request should fail even though the aggregate balance is 150. Whether partial freezing is the right representation depends on the reason for the restriction and who may release it. Freezing is an administrative mechanism; it does not automatically implement the instrument's contractual release schedule.

An ERC-1400 design could represent 100 units in an available partition and 50 in a restricted partition. A request for 120 from the available partition should fail because that partition contains only 100. If the aggregate ERC-20 transfer route can consume multiple partitions, its default selection order and restriction checks must be part of the design. Do not assume the aggregate route behaves like the partition-specific route.

Reduce the request to 40. After a successful transfer that preserves the partition, the sender would have 60 available and 50 restricted; the recipient would receive 40 available. In the partial-freeze model, the sender would have 110 total and 50 frozen, leaving 60 free. Those arithmetic outcomes look similar, but the retained information differs: partition identifiers can carry lot distinctions that one frozen subtotal cannot express by itself.

Now revoke the recipient's eligibility after preview but before execution. Execution must use the applicable current policy; a successful earlier query is not a reservation of eligibility. If the transaction is rejected, balances and associated accounting must remain consistent. If the approved model permits the movement, the record needs to explain which policy and authorization allowed it.

Finally, let the restriction expire. In the freeze model, determine how the frozen quantity is released. In the partition model, determine whether units remain in the same partition with a changed rule or move to another partition. A wall-clock date in a database cannot substitute for an on-chain transition when the contract still blocks the transfer.

Preflight is a snapshot, not a settlement promise

ERC-1594 describes transfer validity queries with error signalling and attached data. Use the exact return values of the implemented interface to build an actionable response. A recipient rejection should lead to an eligibility investigation; a balance rejection should lead to a position check. A failed authorization certificate requires a different operator than either of those.

For ERC-3643, inspecting the compliance result alone leaves out other token conditions. The application needs the relevant identity, freeze, pause and balance checks, with a clear warning when its diagnostic view is incomplete. A callback or external dependency can also fail during execution even if an earlier policy query succeeded.

Store the block identifier used for preview and the instruction parameters. If execution fails later, compare the state and policy changes between the preview and execution blocks. Recomputing against the latest state without preserving the original observation can conceal why the user saw an apparently valid instruction. The user-facing result should name the rejected operation and the next permitted action, without promising that retrying will succeed.

Administrative paths need their own contract

Forced transfers, wallet recovery and redemption are part of the operating model. They must have an authority policy that explains who can invoke them and what ordinary restrictions they bypass. A multisig threshold alone cannot explain whether its signers are allowed to perform a particular correction.

The pinned T-REX token source illustrates why path-specific review matters. Its forced transfer requires agent authority and verifies the recipient. It can release enough frozen tokens to complete the movement and does not call the ordinary compliance pre-check. It does call the post-transfer compliance callback. Those details matter to a module that maintains holder counts or position limits.

The same source's mint path checks recipient verification and the compliance pre-check. This differs from the published specification's explanatory description of mint bypassing compliance rules. Treat the pinned code as the behavior being evaluated and record the discrepancy. A standards summary is not a substitute for examining the deployed entry point.

ERC-1644 describes controller operations and transparency about whether unilateral transfers are possible. A candidate implementation must still demonstrate its exact controller configuration, events and interaction with extensions. Never infer that a controller has the same permissions as an ERC-3643 agent.

For each exceptional path, retain the business authorization, transaction receipt and before-and-after ownership state. A correction transfers ownership in the current ledger; it does not erase the historical transaction. Recovery should preserve the instrument's supply and relevant restrictions while making the old wallet's future role explicit.

Integration includes settlement and document state

ERC-20 compatibility provides familiar calls such as balance and allowance queries. It does not mean that an arbitrary exchange, bridge or escrow contract is an eligible holder. A settlement contract can satisfy the ABI and still fail a recipient eligibility check. Partition-aware integrations additionally need to preserve the intended partition through the complete settlement route.

Test with the actual custody and venue workflow. Does the intermediary support attached transfer data? Can it authorize an operator? Does it display a failure reason to the correct actor? Can its indexer distinguish an ordinary transfer from an administrative movement and reconstruct the relevant balances after a restart?

Delivery versus payment adds a second asset and a settlement boundary. Token eligibility is one condition; cash availability and atomic execution are separate conditions. If policy changes between instruction creation and settlement, the system needs a defined rejection or cancellation result. A selected security-token standard does not make those conditions atomic by itself.

ERC-1643 supplies document references and update events. A URI and content hash can help connect a contract to a particular document. They do not establish that every investor received the document or accepted amended terms. Retain the availability and acknowledgement process separately, with versioned mappings to instrument state.

Redemption also crosses systems. Burning tokens may reduce on-chain supply before an off-chain payment completes. Define whether the workflow escrows units, burns after payment or uses another approved state machine. Reconcile outstanding claims and instrument supply against the administrator's records rather than treating a burn event as proof that cash was delivered.

Require a reproducible selection record

Request the same acceptance cases from each candidate, scoped to the approved instrument. Successful transfers alone are weak evidence. Rejected and exceptional operations reveal whether restrictions remain intact when actors or state change.

Acceptance case	Evidence to retain
Recipient eligibility changes after preview	Policy change, execution result and unchanged balances on rejection
Aggregate balance exceeds spendable balance	Partition or frozen-state snapshot and rejected request
Operator authorization is removed	Revocation transaction and subsequent unauthorized-call rejection
Administrative correction while ordinary transfers are paused	Approved bypass policy, exact path and resulting events
Required attestation issuer is removed	Registry state and expected receipt behavior
Redemption fails in the payment system	Token state, cash state and reconciliation outcome
Policy module or extension changes	Old and new configuration plus affected-case results

These are proposed acceptance cases, not a claim that this article executed a conformance suite. Each implementation should provide its own reproducible fixtures, transaction inputs and expected outcomes. Tests using identity stubs need to say which signature, expiry or revocation behavior they do not cover.

Before release, bind the results to the source commit, compiler configuration, dependency versions and deployed addresses. Include the active identity registries or extensions, privileged-role holders and implementation or proxy relationships. Pinning source makes the comparison reproducible; it does not identify an audited release without matching audit evidence.

The same record needs an operational owner. Name who maintains the investor registry, reconciles settlement exceptions and reviews privileged changes. For certificates, include signer rotation and incident handling. For partitions, include the dictionary of keys and the procedure for introducing a new one. If these jobs belong to different organizations, make their handoffs visible in the acceptance evidence rather than assigning them implicitly to the token developer.

An upgrade needs a before-and-after ownership check that includes restrictions. Equal total supply can hide a lost freeze, a reinterpreted partition or an eligibility registry pointing at the wrong implementation. Rehearse ordinary transfers and exceptional paths against representative outstanding holdings, then reconcile the resulting ownership records.

Record the choice in one sentence with a falsifiable reason. For example: select an ERC-3643 implementation because the instrument has one fungible share class and requires claim-based recipient eligibility plus wallet recovery. Or select the evaluated ERC-1400 implementation because issuance lots must remain explicit through partition-aware custody and settlement. Attach the acceptance evidence that makes the reason true.

When both identities and partitions are essential, evaluate their composition as a separate design obligation. Specify where eligibility is enforced, how restrictions survive partition transitions and which authority may change either rule. The next engineering deliverable is the behavior matrix and reproducible transaction evidence for that exact composition.

About the author

Dmytro Nasyrov. Photo supplied by the author.

Omnibus vs Segregated Wallets: The Ledger Decides

Dmytro Nasyrov — Thu, 01 Oct 2026 05:59:05 +0000

An omnibus wallet and a set of segregated wallets can hold exactly the same assets while supporting different reconciliation claims. The difference appears when a customer balance changes without a corresponding movement between customer wallets. A pool can still match total liabilities. Dedicated wallets can match that total while backing the wrong customers.

Choose the model by the invariant your ledger must prove. For pooled assets, prove aggregate backing and separately validate customer allocations. For strict segregation, also prove that each customer's assigned wallets match that customer's entitlement. A wallet label cannot establish either result.

The required evidence differs.

The example below uses Alice, Bob and 100 synthetic asset units. A complete Python snapshot checker and twelve tests expose an aggregate check that incorrectly approves a segregated allocation. The fixture makes no calls to a blockchain or custody provider.

Separate the wallet, the ledger and the authority

A wallet describes an operational arrangement for holding and moving assets. A customer ledger describes entitlements, reservations and postings. An authority model describes who can approve or sign a movement. These are separate design decisions, even when a provider presents them together in one interface. In a pooled arrangement, several customers' entitlements are backed by assets held in shared wallets. The application needs a private ledger to assign those entitlements. In a segregated arrangement, identified wallets or vault accounts are assigned to individual customers. The ledger still needs to describe spendable balances, pending operations and corrections. The address does not explain those states by itself.

Fireblocks documents these operational models in Create Direct Custody Wallets. Its description distinguishes pooled vault arrangements from individual customer vaults and treats hot or cold storage as another dimension. That distinction matters: segregation does not automatically mean offline signing, and a hot wallet does not automatically mean pooled customer accounting.

The same documentation explains the application-side mapping for a deposit address:

This deposit address is assigned to Alice and mapped accordingly within the customer’s private ledger.

Fireblocks, Create Direct Custody Wallets, official developer documentation, accessed October 1, 2026. The page does not state an exact publication date.

The quoted sentence identifies the missing join: an observed address must be connected to a customer in the ledger. It does not claim that a deposit address proves legal ownership or that every asset uses a separate address for each customer.

This separation also guides the blockchain engineering work at Pharos Production: selecting wallet infrastructure is only one part of specifying how the surrounding application records financial state. The engineering decision needs an entitlement model and a recovery boundary before an address diagram can serve as an acceptance artifact.

Product terminology deserves a second check. Coinbase describes Prime Custody as an omnibus arrangement using its LSOC terminology, while Prime Vault uses dedicated addresses. Those are statements about named products, not evidence that any architecture called segregated has the same contractual treatment. Obtain the applicable custody agreement separately. Neither this article nor its test fixture determines legal title, insolvency protection or the adequacy of a provider's controls.

Compare the evidence each model needs

The useful comparison is between operating requirements. A diagram with one box per customer may be easier to explain, but its proof obligations can be more demanding when the product permits transfers between customers.

Decision dimension	Omnibus arrangement	Segregated arrangement
Customer entitlement	Requires a ledger allocation inside the shared asset pool	Requires a ledger allocation and an explicit customer-to-wallet assignment
Backing check	Compare included pool assets with included customer liabilities	Compare the aggregate and every customer's assigned assets with their liabilities
Internal customer transfer	Can change ledger allocations while the pool remains unchanged	Needs an explicit policy for pending allocation or corresponding wallet movement
Deposit handling	Attribution must survive any sweep into a shared wallet	Attribution must survive wallet creation, reassignment and recovery
Operating constraint	Shared movements obscure customer allocation on-chain	More customer wallet movements can increase transaction and monitoring work
Disqualifier	Cannot satisfy a requirement for exclusive customer wallet backing	Cannot claim strict backing when allocations move ahead of assigned assets

These rows are design consequences of the definitions used here, not a provider performance benchmark. There is no universal winner. Pooling may fit a product whose customer transfers are internal ledger operations. Dedicated wallets may fit a product that requires independently inspectable wallet assignments. Both remain dependent on complete asset inventory and correct postings.

Define the acceptance language before comparing suppliers. If the requirement says customer assets remain identifiable, ask whether that means ledger identification, dedicated wallet assignment, a contractual arrangement, or all three. Each interpretation needs different evidence. A vendor showing balances by customer in a dashboard has demonstrated a view. It has not demonstrated the provenance of those balances.

Also specify the accounting perimeter. A customer asset pool, the operator's own funds, a fee wallet and assets in transit must not be silently added together. A mixed dashboard total can hide an excluded liability or compensate for a shortfall with funds outside the agreed perimeter. Keep the comparison per asset, per network and per cutoff before considering any converted reporting total.

A balanced total can hide the wrong allocation

Start with one synthetic asset. Alice has an entitlement of 60 units; Bob has 40. Total customer liabilities are 100. In the omnibus case, the pool contains 100. In the segregated case, Alice's assigned wallet contains 60 and Bob's contains 40.

Now record a transfer of 15 units from Alice to Bob in the customer ledger. The new entitlements are 45 and 55. Total liabilities are still 100. The following table isolates the wallet movement from the ledger posting:

Snapshot	Alice's ledger	Bob's ledger	Omnibus pool	Segregated Alice/Bob wallets
Opening	60	40	100	60 / 40
Internal entitlement transfer recorded	45	55	100	60 / 40
Corresponding segregated movement completed	45	55	100	45 / 55

An aggregate checker reports zero difference in every row. For the middle row, the segregated checker must report Alice's assigned assets minus entitlement as +15, and Bob's as −15. The aggregate result is correct. The conclusion that segregation is reconciled is incorrect.

There are two coherent ways to handle that middle state. A strict settled-balance policy can keep the customer transfer pending until the required wallet movement completes. A more complex policy can account explicitly for an allocation bridge or receivable. The second option needs its own permitted states, aging rules and reconciliation equations. It cannot borrow the strict model's passing label while omitting the bridge from the report.

The simple checker below deliberately implements the strict snapshot interpretation. It has no bridge account and no transaction state machine. Its rejection means the dedicated wallet amounts do not match the supplied settled entitlements. It does not mean that every temporary mismatch is fraud, loss or an invalid business operation.

For the omnibus row, aggregate equality establishes only that included pool assets equal included customer liabilities. Alice could still be credited incorrectly, or Bob could receive a duplicated posting, while another posting offsets the error. Customer allocation correctness therefore needs independent journal and authorization checks. A pooled report should state that owner backing was not checked, rather than display an empty exceptions list that resembles a successful customer-level check.

Run the snapshot witness and the regression

The aggregate equation is included wallet assets minus recognized customer liabilities. The strict segregated equation repeats that subtraction for each assigned customer. Both must equal zero for this fixture. An excess is a discrepancy too: it may represent an unattributed deposit, an omitted customer liability or funds outside the declared perimeter. The checker does not classify the cause from the sign alone.

Notice that matching every owner implies the aggregate matches only when the inventory and owner mapping cover the same population. Retaining both outputs makes the declared population inspectable and exposes adapter mistakes. The function rejects an assigned owner absent from the position map instead of quietly excluding that wallet from the owner calculation.

Save the next block as reconciliation.py. Amounts are integer base units. Position.total includes reserved units. Reservations reduce availability, not the liability already represented by the total. A wallet row is one included balance observation, identified by a unique name within this materialized list.

from dataclasses import dataclass

@dataclass(frozen=True)
class Position:
    total: int
    reserved: int

@dataclass(frozen=True)
class Wallet:
    name: str
    amount: int
    asset: str
    block: str
    owner: str | None = None

def reconcile(model, positions, wallets, *, asset, block):
    """Pure snapshot witness. Inputs are trusted observations, not fetched here."""
    if model not in {"omnibus", "segregated"}:
        raise ValueError("unknown model")
    for owner, p in positions.items():
        if (not owner or type(p.total) is not int or type(p.reserved) is not int
                or not 0 <= p.reserved <= p.total):
            raise ValueError("invalid position")
    seen = set()
    owner_assets = {owner: 0 for owner in positions}
    for w in wallets:
        if w.name in seen:
            raise ValueError("duplicate wallet")
        seen.add(w.name)
        if w.asset != asset:
            raise ValueError("asset mismatch")
        if w.block != block:
            raise ValueError("cutoff mismatch")
        if not w.name or type(w.amount) is not int or w.amount < 0:
            raise ValueError("invalid wallet")
        if model == "segregated":
            if w.owner not in positions:
                raise ValueError("owner mismatch")
            owner_assets[w.owner] += w.amount
        elif w.owner is not None:
            raise ValueError("owner mismatch")
    assets = sum(w.amount for w in wallets)
    liabilities = sum(p.total for p in positions.values())
    owner_deltas = ({owner: owner_assets[owner] - p.total
                     for owner, p in positions.items()}
                    if model == "segregated" else {})
    delta = assets - liabilities
    return {"asset_total": assets, "liability_total": liabilities,
            "available_total": sum(p.total - p.reserved for p in positions.values()),
            "aggregate_delta": delta, "owner_deltas": owner_deltas,
            "owner_checked": model == "segregated",
            "reconciled": delta == 0 and all(v == 0 for v in owner_deltas.values())}

Save the following as test_reconciliation.py in the same directory. The asset identifier and block label are synthetic constants. The tests exercise distinct outcomes and refusal classes rather than every possible combination of inputs.

import unittest
from reconciliation import Position, Wallet, reconcile

ASSET = "chain-a:token-x"  # Synthetic asset identity, not a live token.
BLOCK = "block-hash-100"   # Synthetic named cutoff, not a live block.

class ReconciliationTests(unittest.TestCase):
    def positions(self):
        return {"alice": Position(60, 0), "bob": Position(40, 0)}
    def wallet(self, name, amount, owner=None, asset=ASSET, block=BLOCK):
        return Wallet(name, amount, asset, block, owner)
    def check(self, model, positions, wallets):
        return reconcile(model, positions, wallets, asset=ASSET, block=BLOCK)
    def test_omnibus_total_matches(self):
        report = self.check("omnibus", self.positions(), [self.wallet("pool", 100)])
        self.assertTrue(report["reconciled"])
        self.assertFalse(report["owner_checked"])
        self.assertEqual(report["owner_deltas"], {})
    def test_segregated_allocation_matches(self):
        report = self.check("segregated", self.positions(),
            [self.wallet("a", 60, "alice"), self.wallet("b", 40, "bob")])
        self.assertTrue(report["reconciled"])
        self.assertEqual(report["owner_deltas"], {"alice": 0, "bob": 0})
    def test_balanced_total_wrong_owner_fails(self):
        positions = {"alice": Position(45, 0), "bob": Position(55, 0)}
        report = self.check("segregated", positions,
            [self.wallet("a", 60, "alice"), self.wallet("b", 40, "bob")])
        self.assertEqual(report["aggregate_delta"], 0)
        self.assertFalse(report["reconciled"])
        self.assertEqual(report["owner_deltas"], {"alice": 15, "bob": -15})
    def test_reserved_is_already_in_total(self):
        positions = {"alice": Position(45, 0), "bob": Position(55, 20)}
        report = self.check("omnibus", positions, [self.wallet("pool", 100)])
        self.assertEqual(report["liability_total"], 100)
        self.assertEqual(report["available_total"], 80)
        self.assertTrue(report["reconciled"])
    def test_asset_shortfall_is_visible(self):
        report = self.check("omnibus", self.positions(), [self.wallet("pool", 90)])
        self.assertEqual(report["aggregate_delta"], -10)
        self.assertFalse(report["reconciled"])
    def test_duplicate_wallet_rejected(self):
        with self.assertRaisesRegex(ValueError, "duplicate wallet"):
            self.check("omnibus", self.positions(), [self.wallet("pool", 50)] * 2)
    def test_mixed_asset_rejected(self):
        with self.assertRaisesRegex(ValueError, "asset mismatch"):
            self.check("omnibus", self.positions(),
                [self.wallet("pool", 100, asset="chain-b:token-x")])
    def test_mixed_cutoff_rejected(self):
        with self.assertRaisesRegex(ValueError, "cutoff mismatch"):
            self.check("omnibus", self.positions(),
                [self.wallet("pool", 100, block="block-hash-101")])
    def test_invalid_reservation_rejected(self):
        with self.assertRaisesRegex(ValueError, "invalid position"):
            self.check("omnibus", {"alice": Position(10, 11)}, [self.wallet("pool", 10)])
    def test_unknown_owner_rejected(self):
        with self.assertRaisesRegex(ValueError, "owner mismatch"):
            self.check("segregated", self.positions(), [self.wallet("pool", 100, "carol")])

    def test_unknown_model_rejected(self):
        with self.assertRaisesRegex(ValueError, "unknown model"):
            self.check("unreviewed", self.positions(), [self.wallet("pool", 100)])
    def test_invalid_wallet_units_rejected(self):
        with self.assertRaisesRegex(ValueError, "invalid wallet"):
            self.check("omnibus", self.positions(), [self.wallet("pool", -1)])

if __name__ == "__main__":
    unittest.main()

Run both files with Python 3.10 or later, which supports the union annotation used above. The recorded local run used Python 3.14.7. The Python unittest documentation describes the command and assertions used here.

python3 -m unittest -v

The regression was first executed against an incomplete aggregate-only version. That version returned reconciled=True for the middle table row, causing test_balanced_total_wrong_owner_fails to fail with AssertionError: True is not false. The correction accumulated assets by assigned owner and required every owner difference to be zero. The same regression then passed, followed by all twelve tests.

Replay of recorded local test output and the recorded correction. This is a synthetic fixture, not a terminal screen recording or a live custody-system test.

The report preserves the distinction between a numerical discrepancy and invalid input. A shortfall produces a report with reconciled=False. Mixed assets, mixed cutoffs, duplicate wallet rows and unknown assigned owners raise errors. A production adapter needs similarly explicit handling, but this function does not establish that its input inventory is complete or authentic.

Reservations and withdrawals need a posting policy

Reserve 20 units for Bob after the transfer, when Alice has 45 and Bob has 55. Bob's available balance becomes 35. Total customer liabilities remain 100, and aggregate available balances become 80. Adding the reservation to the liability total again would report 120 against assets of 100, manufacturing a shortfall.

The reservation test checks this classification only. It does not execute a withdrawal. In a zero-fee illustrative withdrawal that completes for 20 units, assets would fall to 80 and customer liabilities would fall to 80: Alice 45, Bob 35. While the withdrawal is merely reserved, the supplied snapshot still contains the original 100 of liabilities. The accounting transition needs a defined settlement event.

Pharos Production addresses the upstream design choice in its crypto wallet development process, which includes custody-model decisions, threat modeling and recovery design. Those decisions should establish which component may reserve funds, approve a withdrawal and recognize completion. The service description is evidence of that stated process. It is not evidence that this illustrative checker is deployed in a client system.

Specify failure behavior for each boundary. A failed signing request can release a reservation if no asset movement occurred. A submitted transaction with an uncertain outcome needs investigation or a pending state. Releasing the same reservation immediately could make those units available for another withdrawal while the first remains executable. A timeout is an observation about response time, not proof of cancellation.

Fees need an equally explicit rule. If a withdrawal consumes a fee in the same asset, identify whose liability bears it and when that debit becomes final. If the fee uses a different network asset, reconcile that asset separately. Do not conceal it by rounding a converted portfolio value. The example uses no fees so its per-owner mismatch is easy to inspect. A fee policy would extend the fixture and its tests.

Keep availability checks separate from backing checks. The first answers whether a customer may initiate another operation. The second compares recognized obligations with included assets. A customer can have a correctly backed total and no available balance because every unit is reserved. Conversely, an available balance can be overstated even when the aggregate backing report is numerically correct.

Preserve identities through deposits and sweeps

A balance observation needs more identity than an amount and a token symbol. Record the network, the asset identity, the wallet or vault assignment, the source observation and the cutoff. Two assets with the same display symbol must not enter one reconciliation equation merely because the interface renders the same label.

For an ERC-20 token, the standard's balanceOf method returns the balance of an address. It does not return the application's customer identifier. The application must provide that relationship, including the effective period of an assignment. A reused identifier or an incorrect assignment can make accurate chain data answer the wrong customer question.

Fireblocks' deposit-at-scale guidance describes validating deposit observations and maintaining a private ledger after assets are swept. A sweep changes where assets are held. It must not create another customer deposit credit simply because a second wallet received the funds. The credit and the internal asset movement have different accounting meanings.

Build source identity around those meanings. For a token deposit, a transaction can contain multiple relevant events, so a transaction hash alone may be insufficient to distinguish credits. Include the event identity and the adapter's declared network scope. For a provider callback, preserve the provider's operation identity and status history rather than treating every delivery as a new financial operation.

Idempotency then becomes a posting contract: receiving the same recognized deposit twice produces one customer credit. A later status update changes the operation's state under a permitted transition. It does not append another credit by default. A replay check should compare the resulting ledger state and asset inventory, not just count callbacks successfully acknowledged by the server.

The snapshot function rejects duplicated wallet names, but that is a much smaller guarantee. It does not detect duplicated journal entries, verify deposit events, fetch a block, handle a reorganization or prove settlement finality. An adapter must supply observations at the declared cutoff and explain its finality policy. A matching string in every row establishes consistency of the supplied labels, not truth of the underlying chain history.

Signing authority does not replace reconciliation

Separate the ability to move assets from the ability to alter reported obligations. A signing policy can stop an unauthorized withdrawal while a faulty ledger posting still changes customer balances. A perfect journal can coexist with a compromised signer. Review both boundaries because their evidence and failure modes differ.

For each model, identify who may create a customer-to-wallet assignment, who may change it and who may approve exceptions. The reconciliation service should consume a versioned mapping. If an operator silently reassigns Bob's wallet to Alice, a report can change without any asset movement. Retain the previous mapping and the reason for the change so a reviewer can reconstruct the earlier result.

The same principle applies to model selection. Switching a mismatching snapshot from segregated to omnibus removes owner checks and can turn failure into success. That is a change in the promise being evaluated. Require an approved model configuration and bind its version to every report. Do not let a reconciliation operator select the interpretation that produces the fewest exceptions.

Emergency controls need a defined effect on accounting. A pause may prevent new withdrawals while deposits and status observations continue. State whether incoming events are still recorded, whether customer credits remain pending and how reservations are handled. A pause button without these rules can produce a technically stopped service whose ledger keeps drifting.

Recovery should preserve investigation evidence. Before accepting a manual correction, retain the original report, the supporting observations and the proposed posting. Record the correction's author and approval separately from the program that recalculates balances. Then rerun the same invariant under the same perimeter. A balancing entry is not explanatory evidence merely because it reduces the difference to zero.

For segregation, also rehearse a wallet reassignment or recovery operation. Verify that old and new assignments cannot both count the same asset observation, and that the customer's history remains accessible. For pooling, rehearse restoration of the allocation journal from a known point. In either case, a usable backup must support the particular accounting promise, not just restore a wallet service login.

Make the acceptance receipt reconstructable

A supplier demo should hand over a report that another engineer can reproduce. Bind the model version, asset identity, customer perimeter, cutoff, wallet assignments and journal position to the result. Include totals and exceptions together. An empty exception file without the evaluated population cannot establish what passed.

For this fixture, acceptance means recreating the opening balances, applying the internal entitlement change and observing the strict segregated failure. It also means seeing the omnibus report declare owner_checked=False. That boolean is evidence of limited scope. It is not a warning that the pooled model is inherently defective.

Ask for the negative cases before signing off. The wrong-owner case is useful because it preserves the aggregate and challenges the claim that a zero total difference is enough. The shortfall case proves that a real numerical discrepancy remains visible. Invalid-input cases prove that incompatible observations cannot be silently combined into a plausible-looking report.

Keep the reported coverage accurate. The twelve local tests cover snapshot results, reservations and selected validation failures. They do not cover concurrent withdrawals, durable journal posting, signer compromise, provider outages, stale RPC data or inventory completeness. Those requirements belong to the surrounding system and need separate evidence. Passing this suite cannot certify custody safety or accounting compliance.

To extend the example, add one real requirement at a time. If the product allows pending internal transfers between dedicated wallets, specify the bridge account and the permitted duration before implementing it. Write a failure case showing how an expired or unmatched bridge affects acceptance. If the product mixes customer assets with operating funds, first separate the accounting perimeter rather than widening the sum until it balances.

Operational ownership is part of acceptance. Name who investigates a mismatch, which operations may continue and which report releases the restriction. Preserve unresolved cases across restarts. A status page can say a service is healthy while customer backing exceptions remain open. Health and reconciliation are different measurements.

An exception receipt should identify the affected asset and customer, the observed difference, the original cutoff and the next authorized action. If new observations resolve it, retain both results rather than replacing the failed snapshot. If a mapping correction resolves it, preserve the mapping change alongside the recalculation. These records distinguish a late observation from a corrected interpretation. Both may produce a zero difference while requiring different operational responses.

Choose the promise you can keep

Use omnibus custody when pooled backing and an independently controlled customer allocation ledger satisfy the product's actual requirements. Use segregation when the product requires dedicated assignments and can reconcile each customer's assigned assets against recognized entitlements. Evaluate the contractual and signing arrangements alongside that choice, with their own evidence.

The deciding question is what must remain true after a transfer, a reservation, a sweep and a recovery. If the answer requires per-customer backing, require per-customer deltas. If the answer permits shared backing, preserve the allocation journal and state the limits of the aggregate result. A single balance cannot carry both promises without additional records.

Before approving a wallet design, request one trace that leaves the aggregate unchanged while changing customer allocations. Require the team to explain exactly when that trace becomes settled and why the report accepts or rejects it. The 60/40 to 45/55 example supplies a reproducible starting point for that conversation.

For engineers operating dedicated customer wallets: does your system keep an internal customer transfer pending until the assigned assets move, or account for an explicit bridge? What evidence allows that pending state to close?

About the author

Dmytro Nasyrov. Photo supplied by the author.

How to Implement ERC-3643 Transfer Controls for Permissioned Tokens

Dmytro Nasyrov — Wed, 30 Sep 2026 07:46:18 +0000

A permissioned token needs a testable answer to a simple question: why did this movement of tokens succeed? A successful wallet transfer proves little if an agent operation follows different rules, a registry change removes an eligibility requirement or a frontend mistakes a compliance check for complete transaction validation.

This walkthrough implements a recipient-country rule against the actual ERC-3643 contract suite and exercises it with 19 passing tests. It also records a deliberately broken version of the module, the failing regression and the correction. The test fixture uses real token, registry and compliance contracts.

Identity signatures are replaced with explicit test doubles, so the result establishes transfer-control behavior within that boundary.

The distinction between documentation and executable behavior matters here. The ERC-3643 specification describes minting as bypassing compliance rules. The pinned implementation used below calls canTransfer during minting. A release review must resolve that difference for its selected contracts before anyone signs an issuance transaction.

Start with a policy-to-operation map

Write the intended rule before choosing a module. In this example, an ordinary transfer requires an eligible recipient whose registered country appears in an allowlist. Wallet freezes, available balance and the token's pause state remain separate token-level checks. Country values represent registry records maintained by authorized operators; they do not reveal a wallet's physical location.

The implementation question in blockchain engineering work at Pharos Production is how a requirement becomes an observable contract behavior. For this walkthrough, the useful deliverable is a table connecting each rule to a transaction and an assertion. A statement that the token supports compliance cannot tell an integration engineer which call should revert.

Requirement	Enforcement point	Observable test
Recipient has the required trusted claim	Identity registry	Missing claim or removed issuer rejects transfer
Recipient country is permitted	Custom compliance module	Registered recipient in a denied country cannot receive an ordinary transfer
Token is available for ordinary movement	Token pause modifier	Paused transfer fails even when `canTransfer` returns true
Wallet and balance restrictions apply	Token freeze checks	Frozen wallet fails; partially frozen balance retains its boundary
Delegated spending stays bounded	Token allowance accounting	Successful spending reduces allowance; rejected transfer preserves it
Privileged movement has explicit authority	Token agent role	Unauthorized forced transfer fails; authorized exceptional path is tested separately

Decide separately what should happen when an investor's country changes while they already own tokens. This module restricts recipients. It does not automatically confiscate an existing holding, prevent every outbound movement or calculate ownership concentration. Those are different policy decisions and require their own enforcement points and tests.

Pin the contracts before interpreting the standard

The code below targets ERC-3643/ERC-3643 at commit 2f0704dee9658ad9cd5b6ed82e7427da74c28345. Its package identifies version 4.1.3. The compiler is Solidity 0.8.17, with OpenZeppelin contracts and upgradeable contracts pinned to 4.8.3 and the ONCHAINID Solidity package pinned to 2.0.0. This is a reproducible source selection, not a recommendation to deploy an unreviewed repository head.

Read the selected entry points directly. In this version, transfer and transferFrom combine token checks with recipient verification and modular compliance. Do not describe that as universal verification of both participants. If your policy requires renewed sender eligibility on every ordinary movement, add and test that requirement explicitly rather than assuming the recipient check covers it.

The standard's transfer description groups minting with forced transfers as paths that bypass compliance. However, the pinned Token implementation checks canTransfer(address(0), recipient, amount) inside mint. Our mint-denial test captures this behavior. Preserve that test when upgrading the dependency; a changed result needs an explicit issuance-policy decision.

Review inherited behavior and callbacks too. An entry point can omit an ordinary permission check while still reverting in a downstream module action. An interface name alone cannot establish that an operation will succeed.

Make identity requirements explicit

The identity registry documentation separates a wallet's registration from its verification. Registration associates the wallet with an identity and a country. Verification evaluates the required claim topics against the trusted issuer configuration. Keep those responsibilities distinct in onboarding screens and operational runbooks.

A configuration edge case deserves its own regression. In the pinned IdentityRegistry implementation, a registered identity passes verification when the required-topic list is empty. Our fixture first removes a claim and observes rejection. It then removes the sole required topic and observes acceptance. That is configuration behavior, not evidence of a newly discovered vulnerability.

Consequently, checking that every wallet has an identity contract is insufficient for a deployment that requires a particular credential. The release receipt should record the required topics, trusted issuers and each issuer's permitted topics. A reviewer should be able to explain why an empty list is acceptable or show that the deployment rejects that configuration before activation.

Topic 7 is a synthetic identifier in this fixture, not a universal KYC topic. Its issuer stub always accepts the supplied claim, and its identity stub exposes unrestricted setters for test setup. Neither stub belongs in a production deployment. Real signature validation, claim expiry and issuer-specific revocation behavior require a separate integration suite using the chosen identity implementation.

Implement one recipient-country module

Keep this first rule narrow enough to inspect. A mapping answers whether a particular compliance contract permits a particular country. The outer address key matters because a module can serve more than one compliance context. Without that separation, one deployment's policy update could unintentionally alter another deployment's behavior.

The module reads the token bound to the supplied compliance address, then reads the recipient's country through that token's identity registry. The allowlist defaults to rejection. Country zero cannot be enabled through the setter, making the example's requirement for an explicitly configured country visible in code. The fixture uses 250 and 276 as two distinct country values; neither value represents a policy recommendation.

Save the following as src/RecipientCountryModule.sol. It extends the pinned AbstractModule. Configuration requires a call from a bound compliance contract. The check also rejects an unbound compliance context. The transfer, mint and burn action hooks remain access-controlled even though this stateless rule has nothing to update.

// SPDX-License-Identifier: GPL-3.0
pragma solidity 0.8.17;

import "erc3643/compliance/modular/modules/AbstractModule.sol";
import "erc3643/compliance/modular/IModularCompliance.sol";
import "erc3643/token/IToken.sol";

contract RecipientCountryModule is AbstractModule {
    mapping(address => mapping(uint16 => bool)) public allowed;
    event CountryPermissionSet(address indexed compliance, uint16 country, bool enabled);

    function setCountry(uint16 country, bool enabled) external onlyComplianceCall {
        require(country != 0, "country must be explicit");
        allowed[msg.sender][country] = enabled;
        emit CountryPermissionSet(msg.sender, country, enabled);
    }

    function moduleCheck(address, address to, uint256, address compliance)
        external view override onlyBoundCompliance(compliance) returns (bool)
    {
        IToken token = IToken(IModularCompliance(compliance).getTokenBound());
        uint16 country = token.identityRegistry().investorCountry(to);
        return allowed[compliance][country];
    }

    function moduleTransferAction(address, address, uint256)
        external override onlyComplianceCall {}
    function moduleMintAction(address, uint256)
        external override onlyComplianceCall {}
    function moduleBurnAction(address, uint256)
        external override onlyComplianceCall {}
    function canComplianceBind(address) external pure override returns (bool) { return true; }
    function isPlugAndPlay() external pure override returns (bool) { return true; }
    function name() external pure override returns (string memory) { return "RecipientCountryModule"; }
}

A rule based only on recipient country does not need a transfer counter. If you extend it to maximum holders or rolling volume limits, the action hooks become part of correctness. Define how minting, burning and exceptional transfers update that state. Test a revert in a later callback and prove that earlier changes roll back with the transaction. This article's empty hooks cannot establish that property for a future stateful module.

Route configuration through the compliance owner

An operator should not call setCountry directly on the module. The configured compliance owner calls callModuleFunction, which invokes the module so that its msg.sender is the bound compliance contract. This arrangement gives the module the correct policy namespace while preserving the compliance contract's ownership check.

The ModularCompliance implementation evaluates its bound modules in canTransfer. With no modules attached, there is no module-level restriction to reject the transfer. Therefore, a deployment check should assert the intended module set and configured values. A green transaction against an accidentally empty set proves the wrong policy.

Permissioned issuance requires agreement between investor restrictions and executable rules. Pharos Production describes that mapping, including work with the client's legal team, in its tokenization and RWA development process. The engineering handoff should carry the approved policy into explicit module settings and transaction tests. A country allowlist by itself cannot establish that an instrument or offering meets applicable legal requirements.

Prepare the configuration receipt before unpausing. Record the token address, registry address, compliance address and module address alongside the owner and agent assignments. Include the transaction that bound the module and the transactions that set permitted countries. Compare the resulting onchain values with the intended configuration, rather than accepting a deployment script's successful exit status as sufficient evidence.

Build a reproducible local fixture

Use a fresh directory with Git, Node.js, npm and Foundry already installed. The following commands fetch the selected source revision and the pinned dependency versions. Preserve the resulting package lockfile with your test evidence. Review the repository's GPL-3.0 licensing and the licenses of imported dependencies before redistributing or combining the code.

mkdir -p erc3643-controls/src erc3643-controls/test erc3643-controls/vendor
cd erc3643-controls
git clone https://github.com/ERC-3643/ERC-3643.git vendor/erc3643
git -C vendor/erc3643 checkout 2f0704dee9658ad9cd5b6ed82e7427da74c28345
npm init -y
npm install --save-exact --ignore-scripts --no-audit --no-fund \
  @openzeppelin/contracts@4.8.3 \
  @openzeppelin/contracts-upgradeable@4.8.3 \
  @onchain-id/solidity@2.0.0

Save this configuration as foundry.toml. The remappings are necessary because the tutorial imports the actual suite rather than recreating token behavior in a simplified mock. The suite's source files remain under vendor/erc3643; the tutorial's module and tests stay in separate directories.

[profile.default]
src = "src"
test = "test"
libs = ["vendor", "node_modules"]
solc_version = "0.8.17"
optimizer = true
optimizer_runs = 200
remappings = ["erc3643/=vendor/erc3643/contracts/", "@openzeppelin/=node_modules/@openzeppelin/", "@onchain-id/=node_modules/@onchain-id/"]

Below, the complete fixture deploys the actual registry storage, claim-topic registry, trusted-issuer registry, identity registry, modular compliance and token. It initializes each instance, binds registry storage and assigns the agent permissions required by the test. The token receives registry-agent authority for the recovery scenario. Alice and Bob start with registered identities in the permitted country.

Initialization mints 100 indivisible fixture units to Alice and then unpauses ordinary transfers. Using zero decimals makes the balance assertions easy to inspect; production assets need their own denomination and rounding tests. These are directly initialized local contract instances. The fixture does not deploy the suite's proxy factory or validate an implementation-authority upgrade.

Save the complete file as test/TransferControls.t.sol. Every test starts from the same fresh setup, so a policy change in one test cannot make another test pass accidentally.

// SPDX-License-Identifier: GPL-3.0
pragma solidity 0.8.17;

import "erc3643/token/Token.sol";
import "erc3643/compliance/modular/ModularCompliance.sol";
import "erc3643/registry/implementation/IdentityRegistry.sol";
import "erc3643/registry/implementation/IdentityRegistryStorage.sol";
import "erc3643/registry/implementation/TrustedIssuersRegistry.sol";
import "erc3643/registry/implementation/ClaimTopicsRegistry.sol";
import "../src/RecipientCountryModule.sol";

interface Vm {
    function prank(address) external;
    function expectRevert() external;
    function expectRevert(bytes calldata) external;
}

// Test doubles: no signature verification, expiry, revocation list or real KYC.
contract IssuerStub {
    function isClaimValid(IIdentity, uint256, bytes calldata, bytes calldata)
        external pure returns (bool) { return true; }
}
contract IdentityStub {
    address public issuer;
    bool public present = true;
    mapping(bytes32 => bool) public management;
    constructor(address source, address wallet) {
        issuer = source;
        management[keccak256(abi.encode(wallet))] = true;
    }
    function setPresent(bool value) external { present = value; }
    function allowRecovery(address wallet) external {
        management[keccak256(abi.encode(wallet))] = true;
    }
    function keyHasPurpose(bytes32 key, uint256 purpose) external view returns (bool) {
        return purpose == 1 && management[key];
    }
    function getClaim(bytes32 id) external view
        returns (uint256, uint256, address, bytes memory, bytes memory, string memory)
    {
        if (present && id == keccak256(abi.encode(issuer, uint256(7))))
            return (7, 1, issuer, hex"01", hex"02", "");
        return (0, 0, address(0), "", "", "");
    }
}

contract TransferControlsTest {
    Vm constant vm = Vm(address(uint160(uint256(keccak256("hevm cheat code")))));
    address constant ALICE = address(0xA11CE);
    address constant BOB = address(0xB0B);
    address constant SPENDER = address(0xCA11);
    address constant NEW_WALLET = address(0xBEEF);
    Token token;
    ModularCompliance compliance;
    RecipientCountryModule policy;
    IdentityRegistry registry;
    ClaimTopicsRegistry topics;
    TrustedIssuersRegistry issuers;
    IssuerStub issuer;
    IdentityStub aliceIdentity;
    IdentityStub bobIdentity;

    function setUp() public {
        topics = new ClaimTopicsRegistry(); topics.init(); topics.addClaimTopic(7);
        issuers = new TrustedIssuersRegistry(); issuers.init();
        issuer = new IssuerStub();
        uint256[] memory required = new uint256[](1); required[0] = 7;
        issuers.addTrustedIssuer(IClaimIssuer(address(issuer)), required);
        IdentityRegistryStorage store = new IdentityRegistryStorage(); store.init();
        registry = new IdentityRegistry();
        registry.init(address(issuers), address(topics), address(store));
        store.bindIdentityRegistry(address(registry)); registry.addAgent(address(this));
        aliceIdentity = new IdentityStub(address(issuer), ALICE);
        bobIdentity = new IdentityStub(address(issuer), BOB);
        registry.registerIdentity(ALICE, IIdentity(address(aliceIdentity)), 250);
        registry.registerIdentity(BOB, IIdentity(address(bobIdentity)), 250);
        compliance = new ModularCompliance(); compliance.init();
        token = new Token();
        token.init(address(registry), address(compliance), "ControlFixture", "CFX", 0, address(0));
        token.addAgent(address(this)); registry.addAgent(address(token));
        policy = new RecipientCountryModule(); compliance.addModule(address(policy));
        setCountry(250, true);
        token.mint(ALICE, 100); token.unpause();
    }
    function setCountry(uint16 country, bool enabled) internal {
        compliance.callModuleFunction(
            abi.encodeCall(RecipientCountryModule.setCountry, (country, enabled)), address(policy));
    }
    function send(uint256 amount) internal {
        vm.prank(ALICE); token.transfer(BOB, amount);
    }
    function deny() internal {
        vm.expectRevert(bytes("Transfer not possible")); send(10);
        require(token.balanceOf(ALICE) == 100 && token.balanceOf(BOB) == 0, "denial mutated balances");
    }
    function testAllowedTransfer() public {
        send(10); require(token.balanceOf(BOB) == 10 && token.balanceOf(ALICE) == 90);
    }
    function testDeniedCountry() public { registry.updateCountry(BOB, 276); deny(); }
    function testMissingClaim() public { bobIdentity.setPresent(false); deny(); }
    function testIssuerRemoved() public { issuers.removeTrustedIssuer(IClaimIssuer(address(issuer))); deny(); }
    function testPauseIsOutsideCanTransfer() public {
        token.pause(); require(compliance.canTransfer(ALICE, BOB, 10));
        vm.expectRevert(bytes("Pausable: paused")); send(10);
    }
    function testFrozenSender() public {
        token.setAddressFrozen(ALICE, true); vm.expectRevert(bytes("wallet is frozen")); send(10);
    }
    function testFrozenRecipient() public {
        token.setAddressFrozen(BOB, true); vm.expectRevert(bytes("wallet is frozen")); send(10);
    }
    function testPartialFreezeBoundary() public {
        token.freezePartialTokens(ALICE, 85);
        vm.expectRevert(bytes("Insufficient Balance")); send(16);
        send(15); require(token.balanceOf(ALICE) == 85);
    }
    function testTransferFromAllowance() public {
        vm.prank(ALICE); token.approve(SPENDER, 20);
        vm.prank(SPENDER); token.transferFrom(ALICE, BOB, 10);
        require(token.allowance(ALICE, SPENDER) == 10 && token.balanceOf(BOB) == 10);
    }
    function testTransferFromDeniedCountry() public {
        registry.updateCountry(BOB, 276);
        vm.prank(ALICE); token.approve(SPENDER, 20);
        vm.expectRevert(bytes("Transfer not possible")); vm.prank(SPENDER);
        token.transferFrom(ALICE, BOB, 10);
        require(token.allowance(ALICE, SPENDER) == 20 && token.balanceOf(BOB) == 0);
    }
    function testDirectModuleConfigurationDenied() public {
        vm.expectRevert(bytes("only bound compliance can call")); policy.setCountry(276, true);
    }
    function testNonOwnerConfigurationDenied() public {
        vm.expectRevert(bytes("Ownable: caller is not the owner")); vm.prank(BOB);
        compliance.callModuleFunction(abi.encodeCall(RecipientCountryModule.setCountry, (276, true)), address(policy));
    }
    function testForcedTransferBypassesOrdinaryGates() public {
        registry.updateCountry(BOB, 276); token.pause(); token.setAddressFrozen(ALICE, true);
        token.freezePartialTokens(ALICE, 70); token.forcedTransfer(ALICE, BOB, 80);
        require(token.balanceOf(BOB) == 80 && token.getFrozenTokens(ALICE) == 20);
    }
    function testMintChecksCountry() public {
        registry.updateCountry(BOB, 276);
        vm.expectRevert(bytes("Compliance not followed")); token.mint(BOB, 1);
    }
    function testRecoveryPreservesRestrictions() public {
        aliceIdentity.allowRecovery(NEW_WALLET);
        token.freezePartialTokens(ALICE, 20); token.setAddressFrozen(ALICE, true); token.pause();
        token.recoveryAddress(ALICE, NEW_WALLET, address(aliceIdentity));
        require(token.balanceOf(ALICE) == 0 && token.balanceOf(NEW_WALLET) == 100);
        require(token.getFrozenTokens(NEW_WALLET) == 20 && token.isFrozen(NEW_WALLET));
        require(!registry.contains(ALICE) && registry.investorCountry(NEW_WALLET) == 250);
    }
    function testNonAgentForcedTransferDenied() public {
        vm.expectRevert(); vm.prank(BOB); token.forcedTransfer(ALICE, BOB, 1);
    }
    function testEmptyTopicsAdmitRegisteredIdentity() public {
        bobIdentity.setPresent(false); require(!registry.isVerified(BOB));
        topics.removeClaimTopic(7); require(registry.isVerified(BOB)); send(10);
    }
    function testPolicyChangeInvalidatesPreflight() public {
        require(compliance.canTransfer(ALICE, BOB, 10)); setCountry(250, false); deny();
    }
    function testComplianceContextsAreIsolated() public {
        ModularCompliance second = new ModularCompliance(); second.init();
        second.bindToken(address(token)); second.addModule(address(policy));
        require(compliance.canTransfer(ALICE, BOB, 10));
        require(!second.canTransfer(ALICE, BOB, 10));
    }
}

Run forge test -vv from the project directory. The recorded local run on September 30, 2026 compiled the fixture with Solidity 0.8.17 and passed all 19 tests, with no skipped tests. That count describes these named examples. It does not measure exhaustive path coverage, successful mainnet integration or resistance to every adversarial input.

Prove that a denial test can fail

A passing rejection test is more persuasive when it detects a known defect. For the recorded negative run, the module's final check was deliberately replaced with return true. The country-change regression then failed because the expected revert did not occur. Restoring the mapping lookup made that same test pass, after which the complete suite passed again.

--- deliberately-permissive/RecipientCountryModule.sol
+++ corrected/RecipientCountryModule.sol
@@ -20,7 +20,7 @@
     {
         IToken token = IToken(IModularCompliance(compliance).getTokenBound());
         uint16 country = token.identityRegistry().investorCountry(to);
-        return true; // DELIBERATE TEST MUTATION: ignore the recipient country.
+        return allowed[compliance][country];
     }

     function moduleTransferAction(address, address, uint256)

This is a mutation of our tutorial module, not an upstream security finding. Keep the failing output, the correction diff and the passing output together. Otherwise a demonstration can accidentally compare different test selections or lose the source change that explains the result. Both runs used forge test --match-test testDeniedCountry -vv.

Replay of recorded local test output: deliberately permissive tutorial variant, correction and passing checks. The animation summarizes the retained outputs; it is not a terminal screen recording.

The denial helper checks unchanged balances after rejected ordinary transfers. The delegated-spending test also checks that a failed transferFrom leaves its allowance intact. Those assertions connect the error to state, which is more useful than merely observing that some call reverted. Extend this approach to event expectations and downstream accounting when adding stateful modules.

The context-isolation case deserves a precise reading. It binds the same module to a second compliance instance and confirms that the second instance does not inherit the first instance's country permission. Both compliance instances point to the same token solely to keep this probe small. This is a namespace test, not a rehearsal of two separately deployed instruments with different registries and governance.

For a production shared-module deployment, create that second instrument explicitly. Change the first instrument's country rule and verify the second instrument's full transfer result remains unchanged. Then reverse the direction of the change. Include distinct owners and registry data so that an accidental cross-reference cannot hide behind identical fixture values. Those additional cases are proposed extensions, not part of the reported 19-test result.

Review minting and exceptional movement separately

A single assertion that restrictions work hides differences between entry points. The country rule blocks ordinary receipt in the denied country and also blocks minting there in this selected implementation. Our tests exercise both. Forced transfer follows another path: an authorized agent can move tokens while the token is paused and the sender is frozen, without applying this module's ordinary country check.

The fixture freezes 70 of Alice's 100 units, then forces a transfer of 80. The asserted result is Bob holding 80 and Alice retaining 20 frozen units. This concrete balance transition is the reviewed behavior, not a generic statement that an agent can ignore everything. Recipient identity verification still matters, and the token invokes the transfer callback after moving the balance.

Our module's callback is empty. A different module may enforce additional behavior there or revert. Test the complete installed module set before describing forced transfer as guaranteed emergency liquidity. Add explicit negative cases for unauthorized agents and invalid recipients, and test your intended handling of an already frozen recipient. The provided suite covers the unauthorized-agent case; it does not claim those additional recipient cases were executed.

Burning needs its own supply and accounting tests in a production suite. This example implements the required burn hook but does not include a burn scenario. Similarly, the existence of batch entry points does not establish the desired partial-failure semantics for a custody integration. Enumerate the actual entry points the integration exposes and attach an acceptance case to each.

Treat pause and recovery as separate controls

The ERC-3643 authors, including Joachim Lebrun, make pausing an explicit requirement in the specification:

MUST have the possibility to pause the token

For an operator, the useful follow-up is the scope of that pause. Our test proves that compliance.canTransfer can return true while an ordinary transfer reverts because the token is paused. The forced-transfer test proves that an agent operation can still move a balance in that state. An incident runbook must identify which operations remain available after the pause transaction confirms.

Recovery is another privileged workflow. The fixture authorizes the replacement wallet through the identity stub's management-key check, then exercises the actual token recovery function. It asserts movement of the full balance, preservation of a 20-unit partial freeze and the wallet's frozen flag, removal of the old registry association and retention of country 250.

That result does not rotate credentials across every connected service or remove every old key from the identity contract. A real recovery procedure needs separate authorization evidence and updates to offchain custody records. It also needs a negative suite for an unauthorized replacement wallet. The identity stub deliberately makes the positive management-key condition easy to arrange; it cannot establish the security of a real key-management implementation.

A recovery review should also trace permissions across contract boundaries. The local setup grants the token permission to change the identity registry because the recovery operation needs that interaction. Checking only the caller's token-agent role would miss this dependency. Remove the supporting registry authority in a separate deployment rehearsal and confirm that recovery fails without leaving a partially moved balance or a stranded registry entry.

Before restoring service after an incident, compare both balance state and identity state with the approved recovery request. Confirm the replacement address through the organization's established process, then reconcile downstream systems against the final transaction receipt. Reusing a previously approved wallet address from an old support ticket is not sufficient evidence that the current request is authorized.

Give preflight results an honest lifetime

A frontend can ask the compliance contract whether its modules would permit a movement. It should label the result accordingly. The check does not establish adequate allowance, an unfrozen wallet or an unpaused token. Our paused-token test makes that limitation visible without depending on an RPC provider or a race between transactions.

The policy-change test establishes another boundary. It observes a positive compliance check, disables the previously permitted country and then confirms that the ordinary transfer fails. In a deployed system, the state used for a preflight call can change before transaction execution. Avoid turning a simulated result into a promise that the eventual transaction will succeed.

For a transaction preview, simulate the exact entry point with the intended sender, calldata and value against a documented block context. Show the time or block associated with the result, then handle an execution failure as an expected possibility. Preserve the transaction hash and inspect the mined receipt before updating balances as settled. These are integration recommendations; the local fixture does not test a remote provider or mempool ordering.

Failure messages should also preserve the distinction between identity, policy and token state. The pinned token combines some rejection conditions under one revert string. An application may need separate read-only diagnostics to explain a failed simulation, but it should not claim a uniquely established cause when several conditions are false. Keep sensitive identity material out of public error messages.

Make policy changes visible to reviewers

Changing a trusted issuer, removing a required topic or replacing the compliance contract can alter admissible transfers without changing the token's visible name. Treat those operations as changes to the running system's policy. Maintain an inventory of who can perform each one, including any authority that can upgrade the code implementing those permissions.

The custom module emits CountryPermissionSet with the compliance address, country and new value. Retain that context in operational records so that a shared module's event is associated with the right token deployment. Compare observed configuration with an approved baseline after changes. An event stream is useful evidence, but a missed subscription message should not prevent reconciliation from current state and historical logs.

Choose an approval mechanism appropriate to each authority. A multisignature owner may reduce dependence on one key; a timelock may create review time for a configuration change. Neither control automatically governs an agent that retains a separate immediate operation. Draw the complete authority map and test the exceptional route, including who can remove or replace its operator.

Treat changing the allowlist as a release even when no Solidity file changes. Save a before-and-after view, simulate a permitted and a denied movement under the new configuration, and state whether existing holders are affected. Assign responsibility for reconciliation if an operator discovers that a registry country value was wrong. This preserves the connection between the administrative decision and the transfers it actually governs.

The final release receipt should identify the exact source commit, compiler settings, dependency lockfile and deployed bytecode. Attach the configured identities and policy addresses, required topics, trusted issuers, permitted countries and role assignments. Then attach the executed test selection and its limitations. Reviewers need enough information to reproduce the result and enough precision to see what remains untested.

An ERC-3643 implementation is ready for the next engineering review when each permitted movement and each expected rejection has an explicit explanation tied to selected code and configuration. This fixture supplies that explanation for one recipient-country rule and its tested interactions. Expand it around the instrument's real identity system, deployment architecture and authorized operations before treating it as production acceptance evidence.

About the author

Dmytro Nasyrov. Photo supplied by the author.

Verify an Indexer Can Recover from a Chain Reorganization

Dmytro Nasyrov — Sat, 26 Sep 2026 19:57:43 +0000

An indexer can reach the latest block and still serve data from an abandoned chain. Its checkpoint advances, its health endpoint stays green and its token balance includes a transfer that no longer exists in canonical history. Recovery needs a stronger acceptance test: after replacing a branch, every indexed result must match an independent rebuild of the selected canonical history.

This tutorial turns that requirement into an executable rehearsal. A small Python and SQLite model indexes signed amounts, replaces an orphaned suffix and checks its state against a separate pure replay function. The fixture finishes at block B4 with a total of 24. Repeating the same input changes nothing. Injecting an exception during recovery leaves the previously committed state intact.

The example is deliberately bounded. It uses synthetic block identifiers and complete, already selected branches. It does not implement Ethereum consensus, validate block hashes or connect to a node. The database represents one chain and one aggregate. Those limits make the assertions easy to inspect before adapting them to a production indexer with multiple projections and concurrent readers.

The acceptance condition is useful beyond this model. A wallet requires correct ownership and balances; an analytics product requires correct event history and aggregates. Decide which results users depend on before choosing the recovery mechanism.

Define the state that must recover

A checkpoint containing only a height cannot identify a chain. Two competing blocks can occupy the same position. Record the block number together with its hash, then retain enough parent relationships to establish which stored blocks belong to the replacement branch. Treat the checkpoint as a claim about fully committed application state, not merely the most recent RPC response.

For an Ethereum log pipeline, distinguish an observed event from the transaction that produced it. A useful occurrence key contains the chain identity, block hash, transaction hash and log index. The chain identity can live in the database namespace for a strictly single-chain deployment. A transaction hash alone cannot distinguish its appearances across competing histories.

The Geth documentation makes the delivery consequence explicit:

“a subscription can emit logs for the same transaction multiple times.”

Geth documentation, Real-time Events

That statement concerns notification behavior, not a promise that every disconnected consumer will receive every correction. Design storage so repeated observations cannot duplicate an occurrence, while a transaction appearing in a different block can be represented accurately. Its execution context may have changed; do not carry its old derived output into the replacement block without decoding the new receipt.

The blockchain software engineering scope at Pharos Production includes applications whose product behavior depends on off-chain data. A reorganization therefore belongs in the application acceptance criteria: the frontend can display a wrong balance even when every smart contract executed correctly. This tutorial supplies a concrete database exercise for that boundary; it does not claim a measured customer outcome.

Write the recovery contract in terms of visible state. Canonical block membership, active event rows, materialized aggregates and the checkpoint must agree at a committed boundary. If historical orphan records are retained for audit, mark them explicitly and exclude them from current product queries. Deleting them is only one storage policy.

Also specify what a reader can observe during recovery. A single database transaction can present an old committed state followed by a new committed state, subject to the database's isolation behavior. An asynchronous projection pipeline needs a visible generation or watermark instead. Otherwise an API can combine the new event table with yesterday's aggregate and return a result that belongs to neither branch.

Build a fork with a result you can calculate

Use a fixture small enough to audit without trusting the implementation. The shared prefix is G → A1. The old suffix is A2 → A3; the replacement suffix is B2 → B3 → B4. The caller selects the replacement branch. The model never decides that a branch wins merely because it has more blocks.

Block	Parent	Event	Signed units	Role
G	none	none	0	Trusted fixture origin
A1	G	deposit	10	Shared prefix
A2	A1	shared-tx	7	Old occurrence
A3	A2	orphan-tx	-2	Orphan-only event
B2	A1	shared-tx	7	Replacement occurrence
B3	B2	credit	11	New event
B4	B3	debit	-4	Replacement tip

The old total is 10 + 7 - 2 = 15. Undoing its suffix returns the aggregate to 10. Applying the replacement produces 10 + 7 + 11 - 4 = 24. Keeping the old negative event would leave an incorrect result. Keeping both occurrences of the shared transaction would also fail, even if the checkpoint looked correct.

These amounts describe a synthetic signed counter. They are not an ERC-20 balance implementation: there are no addresses, decimals, fees or contract-specific event semantics. Use integer quantities in the model so arithmetic noise cannot obscure a branch identity defect. A real token indexer must define how its decoder maps each event into the relevant accounts and units.

Make the oracle independent of the repair path. The example folds the chosen branch directly into the expected block rows, event rows and total. It never reads the database or calls the rollback code. This catches an indexer that agrees with its own checkpoint while retaining wrong rows. It does not validate a faulty decoder shared by both paths; production replay needs separate golden receipt fixtures for that risk.

An empty block matters too. It advances chain continuity without changing the aggregate. An indexer that checkpoints only blocks containing matching logs has discarded evidence it needs when locating a common ancestor. Keep headers or equivalent ancestry records for the entire retained recovery interval.

Make replacement and checkpoint advancement atomic

The replacement operation first checks that its input is a connected branch from the trusted origin. Each block must extend the previous hash and increment the height by one. It then compares stored block identities with the candidate branch until their shared prefix ends. Everything after that point is subject to replacement.

Bound the amount of history the automatic path may undo. A rollback window is an operational limit, not a claim that deeper reorganizations are impossible. If recovery needs records outside the retained window, stop the normal writer and preserve evidence. Continuing from a guessed ancestor can make a damaged projection look current.

Inside one transaction, remove the losing suffix in reverse block order, reverse its aggregate contributions and append the replacement suffix in forward order. Advance the checkpoint only after the new rows and aggregate updates succeed. Committing those changes together is what makes the checkpoint meaningful. Writing it last without a shared transaction is insufficient when earlier writes can persist independently.

Inverse arithmetic works for this additive projection. It does not automatically work for every business object. Reversing a maximum value, an ownership transition with side effects or an order-dependent state machine may require before-images, versioned entities or a replay from a saved boundary. Test the actual projection algorithm rather than assuming every update has a safe subtraction.

The code uses explicit SQL transaction commands and disables Python's implicit transaction opening with isolation_level=None. See the Python sqlite3 transaction documentation for the connection behavior. This choice keeps the demonstrated boundary visible. It is not a database configuration recommendation for every deployment.

There is one writer in this fixture. A production worker pool needs a fence that prevents an older worker from committing after a newer recovery generation takes ownership. A database lock can serialize writers, but lock acquisition alone does not prove that the worker's fetched branch is still acceptable. Validate the generation or expected checkpoint at the commit boundary.

Run the storage model

Save the following as reorg_harness.py. Block hashes are readable fixture labels; the input contract assumes immutable content for each label. There is no remote I/O inside the transaction. The finalized argument, when supplied, represents an externally verified anchor that the selected branch must contain.

The dApp delivery process described by Pharos Production includes indexer strategy during discovery and indexer deployment during production readiness. The dApp development and indexer delivery process provides a place to assign this rehearsal to a release owner. Passing the local example establishes only the behavior demonstrated below; the deployed storage and RPC adapter still need their own evidence.

import sqlite3
from dataclasses import dataclass

@dataclass(frozen=True)
class Block:
    height: int
    hash: str
    parent: str
    events: tuple = ()  # (transaction hash, log index, signed units)

G = Block(0, "G", "")
A1 = Block(1, "A1", "G", (("deposit", 0, 10),))
A2 = Block(2, "A2", "A1", (("shared-tx", 0, 7),))
A3 = Block(3, "A3", "A2", (("orphan-tx", 0, -2),))
B2 = Block(2, "B2", "A1", (("shared-tx", 0, 7),))
B3 = Block(3, "B3", "B2", (("credit", 0, 11),))
B4 = Block(4, "B4", "B3", (("debit", 0, -4),))
OLD = [G, A1, A2, A3]
NEW = [G, A1, B2, B3, B4]

class Index:
    def __init__(self, path):
        self.db = sqlite3.connect(path, isolation_level=None)
        self.db.executescript("""
        CREATE TABLE IF NOT EXISTS blocks(
          n INTEGER PRIMARY KEY, hash TEXT UNIQUE, parent TEXT);
        CREATE TABLE IF NOT EXISTS events(
          block_hash TEXT, tx TEXT, idx INTEGER, units INTEGER,
          PRIMARY KEY(block_hash, tx, idx));
        CREATE TABLE IF NOT EXISTS state(
          id INTEGER PRIMARY KEY CHECK(id=1),
          n INTEGER, hash TEXT, total INTEGER);
        INSERT OR IGNORE INTO state VALUES(1,-1,'',0);
        """)

    def snapshot(self):
        return (
            self.db.execute("SELECT * FROM blocks ORDER BY n").fetchall(),
            self.db.execute("SELECT * FROM events ORDER BY 1,2,3").fetchall(),
            self.db.execute("SELECT n,hash,total FROM state").fetchone(),
        )

    def sync(self, branch, max_rewind=3, finalized=None, fail_at=None):
        # Input is an already selected, immutable full branch from G.
        if not branch or branch[0] != G:
            raise ValueError("wrong trusted genesis")
        for prev, block in zip(branch, branch[1:]):
            if block.height != prev.height + 1 or block.parent != prev.hash:
                raise ValueError("broken lineage")
        if finalized is not None:
            n, h = finalized
            if n >= len(branch) or branch[n].hash != h:
                raise ValueError("finalized anchor conflict")
        db = self.db
        db.execute("BEGIN IMMEDIATE")
        try:
            blocks, _, state = self.snapshot()
            expected_tip = blocks[-1][:2] if blocks else (-1, "")
            if state[:2] != expected_tip:
                raise ValueError("checkpoint ahead or inconsistent")
            common = -1
            for row, block in zip(blocks, branch):
                if row[:2] != (block.height, block.hash):
                    break
                common = block.height
            if len(blocks) - common - 1 > max_rewind:
                raise ValueError("rewind limit exceeded")
            for n, h, _ in reversed(blocks[common + 1:]):
                removed = db.execute(
                    "SELECT COALESCE(SUM(units),0) FROM events WHERE block_hash=?",
                    (h,),
                ).fetchone()[0]
                db.execute("UPDATE state SET total=total-?", (removed,))
                db.execute("DELETE FROM events WHERE block_hash=?", (h,))
                db.execute("DELETE FROM blocks WHERE n=?", (n,))
            if fail_at == "after_undo":
                raise RuntimeError("injected after undo")
            for block in branch[common + 1:]:
                db.execute("INSERT INTO blocks VALUES(?,?,?)",
                           (block.height, block.hash, block.parent))
                for tx, idx, units in block.events:
                    db.execute("INSERT INTO events VALUES(?,?,?,?)",
                               (block.hash, tx, idx, units))
                    db.execute("UPDATE state SET total=total+?", (units,))
            if fail_at == "before_checkpoint":
                raise RuntimeError("injected before checkpoint")
            tip = branch[-1]
            db.execute("UPDATE state SET n=?,hash=?", (tip.height, tip.hash))
            db.execute("COMMIT")
        except BaseException:
            db.execute("ROLLBACK")
            raise


def oracle(branch):
    # Independent fold: no rollback logic and no database reads.
    blocks = [(b.height, b.hash, b.parent) for b in branch]
    events = sorted((b.hash, tx, idx, units)
                    for b in branch for tx, idx, units in b.events)
    state = (branch[-1].height, branch[-1].hash,
             sum(units for b in branch for _, _, units in b.events))
    return blocks, events, state

The state row deliberately combines checkpoint identity with the materialized total. A wrong total cannot hide behind a correct height in the expected snapshot. The event table has a composite primary key, so a malformed fixture containing the same occurrence twice aborts the transaction instead of silently applying its amount twice.

Repeated delivery is tested at the branch synchronization boundary. Synchronizing an already committed branch skips its existing prefix and leaves the state unchanged. This is different from accepting inconsistent duplicate payloads. A duplicate occurrence inside a newly supplied block is rejected, because accepting conflicting representations of immutable history would conceal an upstream defect.

A full history input keeps the demonstration compact. Production recovery normally fetches only the required headers and suffix, starting from a trusted snapshot or retained boundary. Do not copy the full-history interface into a large deployment without changing its memory, retention and fetch behavior. Preserve the same acceptance conditions when replacing the fixture adapter with a bounded branch reader.

The oracle function is short enough to inspect separately from sync. Its event ordering is deterministic, and it derives the total from the selected input.

Comparing only the final amount would be weaker: unrelated mistakes can cancel numerically. The full snapshot catches a correct total accompanied by stale event identities or an incorrect parent chain.

Exercise recovery, refusal and restart

Save this second file as test_reorg_harness.py beside the first and run python3 -m unittest -v test_reorg_harness.py. It uses the standard library and a temporary database. The ten test methods passed in the local rehearsal for this article. That result is evidence about these fixtures, not a production throughput or durability measurement.

import tempfile
import unittest
from pathlib import Path
from reorg_harness import Index, Block, G, A1, OLD, NEW, oracle

class RecoveryTests(unittest.TestCase):
    def setUp(self):
        self.tmp = tempfile.TemporaryDirectory()
        self.path = str(Path(self.tmp.name) / "index.db")
        self.index = Index(self.path)
        self.index.sync(OLD)

    def tearDown(self):
        self.index.db.close()
        self.tmp.cleanup()

    def test_switch_matches_independent_fold(self):
        self.index.sync(NEW)
        self.assertEqual(self.index.snapshot(), oracle(NEW))
        self.assertEqual(self.index.snapshot()[2], (4, "B4", 24))

    def test_repeated_delivery_is_idempotent(self):
        self.index.sync(NEW)
        once = self.index.snapshot()
        self.index.sync(NEW)
        self.assertEqual(self.index.snapshot(), once)

    def test_reincluded_transaction_has_new_block_identity(self):
        self.index.sync(NEW)
        rows = [r for r in self.index.snapshot()[1] if r[1] == "shared-tx"]
        self.assertEqual(rows, [("B2", "shared-tx", 0, 7)])

    def test_restart_after_each_injected_failure(self):
        for point in ("after_undo", "before_checkpoint"):
            with self.subTest(point=point):
                before = self.index.snapshot()
                with self.assertRaises(RuntimeError):
                    self.index.sync(NEW, fail_at=point)
                self.index.db.close()
                self.index = Index(self.path)
                self.assertEqual(self.index.snapshot(), before)
                self.index.sync(NEW)
                self.assertEqual(self.index.snapshot(), oracle(NEW))
                self.index.sync(OLD)

    def test_deep_reorg_refuses_without_mutation(self):
        before = self.index.snapshot()
        with self.assertRaisesRegex(ValueError, "rewind limit"):
            self.index.sync(NEW, max_rewind=1)
        self.assertEqual(self.index.snapshot(), before)

    def test_finalized_anchor_conflict_refuses(self):
        before = self.index.snapshot()
        with self.assertRaisesRegex(ValueError, "finalized anchor"):
            self.index.sync(NEW, finalized=(2, "A2"))
        self.assertEqual(self.index.snapshot(), before)

    def test_bad_checkpoint_refuses(self):
        self.index.db.execute("UPDATE state SET n=99")
        before = self.index.snapshot()
        with self.assertRaisesRegex(ValueError, "checkpoint"):
            self.index.sync(NEW)
        self.assertEqual(self.index.snapshot(), before)

    def test_broken_parent_refuses(self):
        before = self.index.snapshot()
        with self.assertRaisesRegex(ValueError, "lineage"):
            self.index.sync([G, A1, Block(2, "X", "wrong")])
        self.assertEqual(self.index.snapshot(), before)

    def test_shorter_selected_branch_and_empty_block(self):
        branch = [G, A1, Block(2, "EMPTY", "A1")]
        self.index.sync(branch)
        self.assertEqual(self.index.snapshot(), oracle(branch))

    def test_duplicate_event_payload_aborts_transaction(self):
        before = self.index.snapshot()
        event = ("duplicate", 0, 3)
        import sqlite3
        with self.assertRaises(sqlite3.IntegrityError):
            self.index.sync([G, A1, Block(2, "DUP", "A1", (event,event))])
        self.assertEqual(self.index.snapshot(), before)

if __name__ == "__main__":
    unittest.main(verbosity=2)

The recovery test checks all modeled state against the independent fold. The re-inclusion test isolates the transaction identity problem: only the occurrence under B2 remains active. The duplicate-delivery test verifies idempotency after a successful commit. These failures deserve separate names because a single final-total assertion would make diagnosis harder.

The refusal tests establish a second kind of correctness. When the requested rollback exceeds the configured limit, the indexer must leave its committed state unchanged. The same applies to a conflicting finalized anchor or a broken parent relationship. Refusal is useful only if it is observable to the operator and prevents the worker from advertising itself as caught up.

A corruption fixture changes the saved height to 99 before attempting recovery. The operation rejects that inconsistent starting state instead of treating the number as authority. A production corruption check needs to cover more than the tip: missing earlier rows or a damaged aggregate can survive a superficial checkpoint comparison. Periodic reconciliation and storage integrity checks serve that separate purpose.

A shorter-branch fixture prevents an accidental assumption that height must always increase. It also includes a block with no events. The caller remains responsible for deciding which branch is valid. This test establishes that the storage mechanism can install a supplied connected history, including a shorter one, within its configured rollback limit.

Distinguish an exception from a process crash

Two injected failures interrupt the transaction: one after undoing the old suffix, another after applying replacement events but before advancing the checkpoint. Each raises an exception, triggers a rollback and closes the connection. Reopening the database must reveal the original committed state. A subsequent recovery must then reach the oracle result.

That rehearsal verifies application transaction boundaries. It does not simulate an operating-system kill, a machine restart or loss of durable storage. Claiming crash safety from an exception test would skip precisely the behavior that the database and deployment environment contribute. Keep those evidence categories separate in the release record.

For a process-level extension, run the real worker against an isolated test database and terminate it at instrumented boundaries. Reopen through the normal startup path, then compare its state with the saved canonical fixture. Include termination immediately after commit but before the worker acknowledges success. Retrying that work must not duplicate rows or external deliveries.

Use deterministic barriers rather than timing guesses. A test coordinator can wait until a worker reports that it has reached a specified boundary, then trigger the failure. Record whether the signal occurs before a write, after a write or after commit. A sleep followed by termination rarely establishes which transaction state was actually exercised.

Repeat this with the production database engine, transaction isolation and deployment configuration. If projections live in separate stores, one local transaction cannot provide atomicity across all of them. A versioned publication barrier or an explicitly reconciled workflow must cover that gap. Test readers as well as writers: the API should expose a consistent generation or an honest recovery status while downstream projections catch up.

Reconcile the provider before trusting the next event

An event subscription is a useful notification channel, but it should not be the only recovery record. Geth documents connection-bound subscriptions and the absence of historical event delivery. After reconnecting, reconcile the saved checkpoint against the node's current canonical chain and backfill the required interval. Receiving a new notification proves that the connection works; it does not prove that the gap was empty.

Ethereum's JSON-RPC reference exposes block identity and parent identity, along with log fields and block-based lookup methods. An adapter should preserve those identities throughout acquisition. A numeric range fetched while the head changes can otherwise mix observations from different histories. Test the adapter with deliberately inconsistent responses, including a receipt whose block identity does not match the expected header.

One practical acquisition contract is to capture a target block identity, walk its parent-linked history and verify each returned object against the expected hash. Revalidate the target against the provider's canonical view before publishing the recovered generation. If the target changed, abandon or restart that attempt according to the adapter's bounded retry policy. The chain can change again later, so repeated reconciliation remains necessary.

Where the provider supports log queries restricted to a block hash, use that identity to reduce ambiguity. Where it only supplies ranges, validate each result and recheck the associated headers. An empty result is not automatically proof of complete history: the provider may have limited retention, truncated a response or failed a request. Preserve explicit completion evidence for the fetch contract your provider actually offers.

Add a second fork during recovery to the adapter suite. Also test reconnects, duplicate notifications and switching to a provider with a different observed head. The desired result is either a coherent committed generation or a bounded refusal. A mixture assembled from two provider views should never pass merely because all requested heights were returned.

Give finality and external effects separate policies

Confirmation depth and protocol finality answer different questions. A configurable number of later blocks is an application risk policy; it is not a universal finality guarantee. Ethereum's Gasper explanation describes how justified and finalized checkpoints relate to fork choice. Map your application's publication boundary to the actual chain and provider semantics you operate.

The JSON-RPC API includes safe and finalized block tags, but a product spanning multiple networks must verify support and meaning for each network. In particular, a rollup's observed execution head and its settlement conditions require network-specific treatment. Do not reuse an Ethereum execution-layer assumption as proof of settlement on another system.

The model's finalized-anchor check is intentionally conservative. If the selected branch conflicts with the externally supplied anchor, it refuses mutation. An operator then investigates the provider, chain identity and saved anchor. The model does not explain how to resolve a consensus failure or choose between conflicting trusted sources.

A database rollback also cannot retract an email already delivered or automatically reverse an action in another system. Store outbound work with its originating event identity and recovery generation. Decide which effects wait for the relevant finality policy, which can be canceled before dispatch and which require a separately authorized compensation process after dispatch.

Test the dispatcher race explicitly. A queued event can become orphaned between selection and delivery. A local validity check narrows that window but cannot make a remote action atomic with chain consensus. For consequential effects, the acceptance contract must state the remaining exposure and the permitted response. Avoid promising exactly-once real-world behavior from a database uniqueness constraint.

Retain the evidence needed for the next rollback

History retention sets a practical limit on recovery. If the database keeps only current entity values, it may lack the information required to reverse an old transition. Define the retained header interval together with the event journal, decoder versions and any projection snapshots. Keeping headers longer than the data needed to rebuild their effects does not extend the usable recovery window.

Rehearse pruning as part of the lifecycle. Build a snapshot at a verified boundary, retain the required suffix and prove that replay from that snapshot produces the same state as the full fixture. Then present a fork whose ancestor lies before the retained boundary. The expected result is an explicit recovery-plan failure, not a partial rewind followed by a successful health check.

Keep operational watermarks separate from retention policy. A consumer finishing a block does not necessarily mean every dependent projection or outbound queue has finished using its evidence. Document which components must acknowledge a generation before its journal becomes eligible for pruning. Otherwise a routine cleanup can remove the very rows an incident runbook assumes are available.

Keep a release receipt that can be rerun

A useful recovery receipt identifies the software revision, database configuration and fixture hashes. It records the old checkpoint, common ancestor and selected target, then stores the expected and observed projection snapshots. Save a structured diff when they disagree. A log line announcing completion cannot replace that comparison.

Measure operational behavior separately from logical correctness. Record the rollback depth, recovery duration, backlog and time until each public projection reaches the recovered generation. Set budgets from the product's requirements and actual workload. The tiny fixture here supplies no defensible latency target for a deployed indexer.

Before release, run the same acceptance contract through the real decoder, storage adapter and API read path. Include a replay from a retained snapshot so missing historical data becomes visible before an incident. Confirm that an operator can recognize a refusal, preserve evidence and resume from an approved boundary without editing the checkpoint by hand.

The release gate is concrete: the supported reorganization cases converge to independently expected state, repeated work has no additional effect and interrupted work resumes without exposing mixed generations. Unsupported depth or conflicting finality evidence produces an explicit stop. Keep the failed fixtures as regression tests; they describe the exact circumstances under which a green health check once failed to tell the whole story.

About the author

Dmytro Nasyrov. Photo supplied by the author.

Healthcare RAG: Test the Claim-to-Source Contract

Dmytro Nasyrov — Sat, 26 Sep 2026 08:18:29 +0000

A healthcare RAG answer can carry a working citation link and still fail review. The page exists, the passage loads and the answer sounds reasonable. Yet the passage may support only half the sentence, belong to an older edition or describe a different population. A link check cannot resolve those failures.

Before accepting a retrieval-augmented generation feature, specify a claim-to-source contract: what the product retains about each assertion, which checks it performs and what the user sees when a check fails. Treat that contract as a deliverable shared by ingestion, retrieval, answer rendering and review. The schema and acceptance cases below describe a proposed implementation for an educational healthcare knowledge product. They are not a clinical validation or a report of a deployed system.

Start with an assertion that can fail

Consider a fictional learning assistant whose approved handbook describes how a training module is organized. A generated answer says that the module has an introductory lesson and an assessment. The cited passage describes the lesson but says nothing about assessment. Every component can appear healthy: ingestion succeeded, retrieval returned a relevant passage and the link opens the right page.

The unsupported addition is still visible to the learner.

Your first acceptance rule should therefore operate on assertions, rather than on paragraphs that happen to end with a reference. Divide independently checkable statements into separate claims. Retain which passage supports each one, including any qualification needed to keep its meaning intact.

Do not assume one sentence equals one claim. A sentence can combine a population, a benefit and a comparison. Conversely, one claim may require two passages read together. Let the representation support a set of evidence references and explain why that set is sufficient. A mechanical requirement for exactly one reference would force the content into the wrong shape.

The ALCE research paper evaluates fluency, correctness and citation quality as separate dimensions. That distinction is useful for an acceptance plan: polished output and correct links are insufficient evidence of supported claims. The practical design decision here is to retain those checks separately so an attractive answer cannot hide a failed evidence check.

For teams commissioning this work, the boundary between a prototype and an implementation should also appear in the statement of work. The software product development scope should identify which evidence interactions are demonstrated and which are backed by working retrieval. A reviewer needs to know whether an opened passage was handpicked for the demo or selected by the system for that request.

Keep evidence identity separate from its location

A source URL is a locator.

It is not enough to identify the exact material behind a saved answer. The same address can serve a corrected document tomorrow. A source record should distinguish the publisher's identifier, the retrieved version and the particular passage used in an answer.

For a document corpus, retain a content fingerprint with the ingestion run. Bind extracted passages to that fingerprint and to an extraction version. A new extraction can change reading order or table structure even when the original file has not changed. Without both identities, a reviewer may be comparing an old answer against new extracted text without realizing it.

Page labels need similar care. A viewer's page index and the number printed on a book page can differ. Front matter can use a different numbering system. Store each independently and verify their mapping during ingestion. A fixed subtraction is appropriate only when the source actually has a verified fixed offset. Otherwise use an explicit page map, including pages without printed labels.

The passage should retain enough context to inspect its qualifications. Extracting a sentence while dropping a table heading can remove the population or unit that makes it meaningful. Preserve the relevant parent heading, table headers and footnotes with a reference to the original location. If extraction cannot capture the context, mark that passage for review before using it as answer evidence.

Here is a compact record shape. Values are synthetic and the identifiers intentionally describe test fixtures. This is a data contract, not a ready-made clinical schema:

{
  "answer_id": "fixture-answer-01",
  "answer_version": 1,
  "corpus_snapshot_id": "fixture-corpus-a",
  "policy_version": "education-only-v1",
  "claims": [{
    "claim_id": "c1",
    "text": "The module contains an introductory lesson.",
    "evidence_refs": ["p1"],
    "support_status": "pending_review"
  }],
  "passages": [{
    "passage_id": "p1",
    "source_id": "fixture-handbook",
    "source_version": "fixture-edition-a",
    "content_fingerprint": "fixture-fingerprint-a",
    "extraction_version": "fixture-extractor-a",
    "source_class": "handbook",
    "locator": {"viewer_page": 9, "printed_page": "3"},
    "text": "This module begins with an introductory lesson."
  }],
  "review": null
}

In an implementation, validate the fingerprint's real algorithm and format; the fixture string above is only a readable stand-in. Likewise, a support label is a decision to justify. It does not become true because a generator emitted the field. Store the verifier or reviewer decision separately and bind it to the answer version it actually examined.

Give structural checks a narrow job

Deterministic validation can establish whether referenced records exist, whether identifiers are unique and whether a page mapping resolves within the identified document. It can reject an answer with a dangling passage reference before the renderer builds a citation marker. Those are useful guarantees because they have precise failure conditions.

This Python function implements only the reference-integrity portion, assuming the record has already passed type and required-field validation:

def reference_errors(record):
    claims = record["claims"]
    passages = record["passages"]
    errors = set()
    claim_ids = [c["claim_id"] for c in claims]
    passage_ids = [p["passage_id"] for p in passages]
    if len(set(claim_ids)) != len(claim_ids):
        errors.add("duplicate_claim_id")
    if len(set(passage_ids)) != len(passage_ids):
        errors.add("duplicate_passage_id")
    known = set(passage_ids)
    for claim in claims:
        refs = claim["evidence_refs"]
        if not refs:
            errors.add("missing_evidence_ref")
        if any(ref not in known for ref in refs):
            errors.add("dangling_evidence_ref")
    return sorted(errors)

I checked this function locally against the synthetic receipt and four mutations: a duplicated claim identifier, a duplicated passage identifier, an empty reference list and an unknown reference. The control returned an empty list; each mutation returned its corresponding error. Those five checks establish the illustrated reference behavior only. They do not verify source authenticity, passage meaning, access policy or page mapping. An empty claim list also needs a separate product rule if the caller expects an answer.

String matching cannot establish that a clinical statement is justified. Exact copying can omit a negation immediately before the excerpt. A correct paraphrase can share few words with its source. Keep a distinct semantic review stage with a written rubric for support, contradiction and unresolved cases.

For the fictional fixture, a structural check should resolve c1 to p1, confirm the passage belongs to the declared corpus snapshot and verify that its locator opens the intended source version. A semantic review should compare the claim with the complete passage context. Adding an assessment to the claim should fail that review while leaving the structural result unchanged.

This separation makes failures diagnosable. If the source cannot be opened, investigate source availability or access. If the wrong page opens, investigate the locator. If the correct page opens but does not support the claim, investigate generation or the support decision. Routing every problem into one hallucination counter discards information the team needs to repair it. Define the review unit before calculating any percentage. Citation completeness asks whether claims that need evidence have it. Support correctness asks whether the attached evidence supports those claims. A dashboard should name the denominator and preserve unresolved cases rather than silently removing them. Otherwise a system can improve its reported score by making difficult claims disappear from the evaluation set.

Make source authority an explicit constraint

A handbook explanation, a research finding and a regulatory record answer different questions. A product should preserve those source classes through extraction and rendering, instead of reducing them to interchangeable links. The reviewer must be able to tell what kind of evidence is attached before interpreting what it establishes.

An article about a device cannot stand in for a regulator's record of that device's status. A regulatory record cannot, by itself, support every claim about comparative effectiveness. In your source policy, define which class may support which assertion type and require review when an answer crosses that boundary. Keep jurisdiction and retrieval date visible where they affect interpretation.

This distinction appeared during Pharos Production's healthcare AI design work. Our published case reports that an audit found 6 of 7 demo citations wrong, including 4 invented citations. These were findings about our own mockups, not measurements of a deployed model. The response included verified source passages and separate presentation of handbook, research and regulatory evidence.

The healthcare AI citation UX case study shows the source audit and illustrative screens behind those decisions, including the work still outstanding. Use it when reviewing an implementation proposal: compare the proposed evidence panel with the concrete design problems the case documents. The engagement remains in the design phase; external retrieval connectors shown in the demo are planned, not live.

For an engineering team, the next step is to turn a chosen source policy into fixtures. Create a claim that uses the right passage under the wrong source class. The acceptance result must expose that mismatch even if the text appears relevant. Source authority should survive a rendering refactor and a retrieval-provider change.

Separate support from permission to answer

A supported statement can still be inappropriate for the product's intended use. An educational assistant should not drift into patient-specific treatment instructions because a passage contains information that looks relevant. Keep the source-support decision separate from the policy decision governing what this product may present.

That separation needs visible states. A missing source, an unavailable source service and a request outside the product's permitted scope are different situations. The user needs a different explanation and next action for each. Internally, retaining separate reasons prevents the team from trying to fix a policy refusal by increasing the number of retrieved passages.

The FDA's January 29, 2026, guidance discusses enabling a healthcare professional to "independently review the basis" for recommendations. That phrase concerns one part of the US non-device clinical decision support criteria; a citation interface alone does not establish a product's regulatory classification. The current FDA guidance is the source for that boundary, rather than a certification supplied by this design pattern.

For the proposed educational product, define a policy result alongside the support result. A fully supported explanation can proceed only when its use is allowed. An unresolved support decision should remain visibly unresolved. A denied use should select the intended boundary response even if retrieval found relevant material. Have the responsible domain owner approve that behavior before teams encode it in templates.

The priority between states also matters. Suppose retrieval times out on a request the product must not fulfill. Retrying the request automatically could produce prohibited output when the service recovers. Evaluate the intended-use boundary independently and avoid making an infrastructure error the only reason the answer was withheld.

Build a small fixture suite with explicit oracles

Start with a bounded corpus you are entitled to use and questions whose expected evidence can be inspected. Each fixture needs a reason it belongs in the suite, an expected user-visible outcome and an owner for disagreements. A collection of convenient questions without answerability labels will not reveal whether the product refuses too often.

Keep synthetic examples visibly synthetic.

Use neutral learning-content statements for plumbing tests so a malformed fixture cannot be mistaken for medical advice. Domain-specific acceptance cases need appropriately qualified review and controlled source material. Do not copy sensitive patient information into a shared test repository simply because a scenario would look more realistic.

The following matrix is a proposed starting point. Its rows represent different failure classes, not a measured test result or a completeness claim:

Fixture	Deliberate condition	Required observable result
Supported control	Approved learning claim with an exact supporting passage	Claim displays and its marker opens the correct version and location
Unsupported addition	Add an assertion absent from the otherwise relevant passage	Added assertion is withheld or enters review; the supported part remains distinguishable
Locator mismatch	Keep the passage text but point to another printed page	Citation validation fails; the interface does not present the location as verified
Authority mismatch	Attach an assertion to a source class that cannot establish it	Source-policy failure is visible and retained in the receipt
Source unavailable	Make the evidence service unavailable for the request	An availability state appears; no fabricated passage fills the gap
Covered question missed	A gold passage exists but the retriever misses it	Evaluation records a retrieval miss rather than treating the refusal as success
Intended-use boundary	Ask the educational product for a patient-specific directive	Approved boundary response appears, independent of source availability
Changed source	Replace a source version behind a saved answer	The saved evidence remains identifiable and its review status is reconsidered

Run the supported control alongside negative cases. A system that suppresses every answer can pass many refusal tests while failing its main purpose. The covered-question fixture provides a second safeguard: the absence of retrieved evidence does not prove the absence of evidence in the corpus.

For each failure, check both the visible result and the retained record. A correct warning with a misleading success status in the receipt is still a defect. A correct internal rejection with an unsupported claim left on screen is also a defect. The acceptance oracle spans the service boundary and the rendered answer.

Exercise the contract through the user interface

Component tests should prove that a claim marker opens its bound passage, rather than whichever passage happens to occupy the same array position. Reorder the evidence list while preserving its identifiers. The marker must still lead to the same evidence. This catches a simple implementation mistake with consequences that a visually unchanged snapshot may miss.

Also test the path back to the answer. After inspecting a passage, a reader should retain the context of the claim they were checking. If the interface opens a large document at its beginning, the citation may be technically reachable but practically difficult to review. Record that as a usability finding instead of converting it into an invented accuracy metric.

Use representative intended users for that review. Ask them to locate the evidence, explain what it supports and identify a qualification. Observe where they mistake source provenance for review approval or assume a familiar publisher validates the whole answer. The product owner should decide what failure in that task blocks acceptance; a developer should not infer the threshold from a click-through rate.

Mobile layouts deserve the same evidence identity checks. A compact popover may omit the source edition that appears in a desktop rail. A downloaded or copied answer may lose the marker entirely. Specify which export formats preserve traceability, then verify them. If a format cannot preserve it, the exported artifact should make that limitation apparent to its reader.

Accessibility belongs in the acceptance scope too. A visual connection drawn by color alone does not tell every reader which claim is selected. Give markers descriptive names, support keyboard navigation and verify focus behavior when an evidence panel opens and closes. These are proposed product requirements that need testing in the actual implementation.

Invalidate review when its inputs change

A review decision should refer to an answer version, its evidence versions and the policy under which it was accepted. Changing any of those inputs can invalidate the decision. Avoid a permanent approved flag attached only to the conversation, because later answers can inherit approval for content nobody reviewed.

For example, a reviewer accepts the synthetic lesson claim against edition A. An editor publishes edition B and moves the passage. Keep the old answer and its original evidence identity available under the applicable retention policy. Create a new review event for the changed source relationship. Do not silently rewrite the old receipt until it appears to describe edition B all along.

Some changes require semantic review; others need narrower checks. A viewer-coordinate correction with unchanged passage content may need locator verification. A changed qualification requires reassessment of support. A new intended-use policy requires reassessment of permission even if the text is identical. Write these invalidation rules down so routine maintenance has predictable scope.

The same rule applies to model and retrieval changes. Passing the contract tests on a new configuration establishes only the tested behavior for that configuration and fixture set. Preserve the model identifier and relevant retrieval settings with the run. If a provider cannot guarantee identical future behavior behind an identifier, record that reproducibility limit rather than promising exact replay.

Budget for the review work the schema cannot perform

Mechanical checks are cheap to repeat once the representation is stable. Semantic review has a different cost and requires an agreed rubric. An automated verifier can help prioritize disagreements, but its output needs evaluation against the domain reviewers' judgments. Agreement on familiar examples does not establish reliability on unsupported, ambiguous or contradictory ones.

Assign ownership at the point where a decision can become stuck. The ingestion owner resolves missing context. The product owner decides whether the intended user can complete the evidence task. The domain reviewer judges whether the claim is supported within its scope. Engineering preserves those decisions and makes the software follow them. One undifferentiated review queue makes these responsibilities harder to see. Set an unresolved-case policy before measuring performance. If reviewers disagree about whether a passage supports a claim, keep that uncertainty in the fixture metadata. It can be a useful test of the escalation route. Forcing consensus merely to obtain a tidy score removes the scenario that needs the clearest product behavior.

Measure operational burden as well as answer quality. Count cases awaiting review and record why they remain open. Track whether the evidence panel gives reviewers enough context to decide without searching an unrelated document store. Use those observations to improve the workflow; do not describe shorter handling time as proof of safer clinical decisions.

Retain evidence without retaining everything

An auditable answer does not require copying every input into an unrestricted log. Decide which records belong in the evidence store, which belong in a restricted operational system and which should not be retained. The educational fixture can be public because it contains invented learning content. A real request may carry information that changes those decisions.

Give the receipt stable references to protected records where appropriate. Apply access checks when the evidence panel resolves them. A citation should not become an alternate route around the permissions that protect the underlying document.

Test this with an authorized reader and a reader who cannot access the same source; the second reader must not receive the passage through a cached answer.

Retention also creates an acceptance edge case. If the supporting document is no longer available under the applicable policy, the product cannot honestly present the saved answer as fully inspectable. Preserve the reason for that limitation without inventing a replacement passage. The owner needs to decide whether the answer remains visible with a warning, becomes restricted or is removed through the established retention process.

Agree on that behavior before promising reproducibility in a delivery contract. Exact replay may depend on source licenses, retained snapshots and provider behavior outside the application's control. A useful receipt states what can still be verified today and what was verified at the original review. Those are different claims, and a buyer should be able to distinguish them without investigating your storage architecture.

Put the evidence contract in the delivery packet

For a healthcare AI development proposal, request the schema, the source-version policy and the fixture matrix together. Require a sample answer receipt that can be followed from the rendered claim to its source passage. Ask for both a passing control and a failure that remains visible to the user. Those artifacts make an implementation scope concrete enough to inspect.

The packet should also name what has not been demonstrated. A clickable prototype, a working ingestion job and a tested retrieval path are different deliverables. Record which one exists, which sources it uses and who accepted its limits. That gives the buyer a basis for deciding what the next development milestone must prove.

Before commissioning the next phase, bring an authorized sample corpus, a representative learning task and a named review owner to the technical discussion. Use the case linked above to examine the discovery work, then use this contract to ask how the implementation will preserve it. A credible proposal should identify the first claim it will prove, the fixture that can break it and the person responsible for resolving the failure.

About the author

Dmytro Nasyrov. Photo supplied by the author.

ISO 20022 Address Migration Is a Data-Lineage Problem

Dmytro Nasyrov — Thu, 24 Sep 2026 05:12:22 +0000

A payment can carry a plausible town and country while nobody can explain where either value came from. The XML may validate. The address may look cleaner than the original. Yet the migration has created an operational liability: an investigator cannot distinguish customer supplied data from a parser's guess, or reproduce the decision after the customer record changes.

ISO 20022 address migration needs field level lineage. Every outgoing address component should remain connected to its source revision, the relevant payment party, the transformation that produced it, and the rules used to approve its use. This article develops a six-gate engineering runbook for that connection, including a synthetic evidence record and a rehearsal that deliberately breaks it.

First, correct the migration calendar

Status checked on September 24, 2026: the previously advertised November 2026 cutover is no longer a reliable universal planning assumption. Swift's current extension announcement says:

“Swift will defer all payments changes.”

That statement comes from Swift's structured address migration announcement. Swift is consulting on the timing and approach for structured addresses and promises an update by December at the latest. Its separate Q1 2027 timing for securities, trade and other changes must not be substituted for a payments address deadline.

The Bank of England's current RTGS and CHAPS implementation page also says the November 2026 release has been deferred in its entirety. Its expectation is a twelve-month deferral into November 2027, including removal of unstructured address fields, subject to confirmation and wider validation. That is a qualified expectation for that implementation, not a confirmed global Swift deadline.

This matters architecturally. A rule package, its approval status and its activation date are different facts. A migration service that hardcodes a date from an old presentation has already lost one kind of provenance. Keep the document reference, retrieval date, applicable scheme and activation decision alongside the rules. Continue improving address capture while the external timetable changes.

What the six gates establish

The useful delivery unit is an address decision with evidence. A database backfill count alone cannot show that the correct party's address reached the correct message field. The following gates provide an internal acceptance contract; they are a proposed engineering design, not a Swift certification procedure.

Gate	Question to answer	Evidence required to proceed
1. Source	Which record did this decision use?	Versioned source reference and capture context
2. Party	Whose address is being represented?	Stable party identity, role and address purpose
3. Meaning	What supports each structured value?	Field mapping, evidence and unresolved ambiguities
4. Rules	Which requirements were applied?	Scheme profile, version and activation decision
5. Transport	What reached the outgoing message?	Field comparison across every relevant adapter
6. Operations	Can the decision be investigated and replaced?	Exception ownership, revision history and rehearsal receipt

These gates span data ownership, payment orchestration and integration. That boundary is why financial software development needs an explicit migration acceptance contract. Pharos Production lists financial systems among its development services; the procurement question is which team will own the evidence across those systems, including the interfaces outside a supplier's immediate codebase.

A useful implementation produces one linked record at each gate. It also permits a stop. Missing country evidence should create a visible exception with an owner. Quietly filling the field may improve a completeness dashboard while making the next investigation harder.

The six gates preserve the path from a source revision to a message decision. An exception returns through validation after correction.

Gate 1: capture a source revision you can retrieve

Begin with an inventory of where addresses enter the payment flow: customer onboarding, beneficiary maintenance, enterprise resource planning imports, treasury files and service APIs. For each source, identify the owner and whether it contains structured fields, free text or both. Separate what the system stores from what an upstream team believes it stores.

Use a source reference with a stable record identifier and an immutable revision. A pointer to the latest customer profile is insufficient. If the customer changes an address tomorrow, an investigation of yesterday's payment still needs the version used yesterday. Capture both the source's effective time, when known, and the time your system observed it. A late correction can make those timestamps differ substantially.

Preserve the original representation inside an appropriately controlled evidence store. The operational event can carry an opaque reference and an integrity digest instead of another copy of the full address. A digest establishes whether bytes changed; it does not establish that the address was accurate, collected lawfully or associated with the right person.

Define retention, access and retrieval together. A lineage identifier that points to an expired object may be useless during an investigation. Conversely, retaining every raw import indefinitely creates unnecessary personal data exposure. Agree the evidence lifecycle with the responsible data and compliance owners, and make expiry an explicit state that downstream systems can recognize. Test the boundary with a mundane change: revise the source record between extraction and serialization. The release path should detect the revision mismatch and re-evaluate the address. It should never combine the old street with the newly edited country merely because both values were individually available in a cache.

Gate 2: bind the address to a payment party

An address without a role is easy to misuse. A corporate profile may contain a registered office, an operating location and a correspondence address. A payment instruction may identify the debtor, creditor, ultimate parties and several financial institutions. Those relationships need explicit modeling before any text is parsed.

Use a binding that includes a stable party identifier, the role in this payment context and the address purpose selected under the applicable policy. Store the selection reason. Avoid joining records by display name: two subsidiaries can share a trading name, while one legal entity can have several legitimate locations.

The distinction also affects requirements. Swift's corporate address guidance describes hybrid addresses with structured town and country, plus up to two address lines without duplicating the structured elements. It explains that a beneficiary bank identified by BIC generally does not also require its postal address. Apply those format and role distinctions using current scheme guidance; the same FAQ still contains older November 2026 wording, which the extension announcement supersedes for scheduling.

Do not generalize an agent's BIC exception into permission to omit a creditor address. Equally, do not manufacture a bank address merely because a common internal object has mandatory address properties. Model applicability explicitly so that absent, unknown, required and not applicable remain distinguishable states.

A useful negative fixture contains two parties with the same town but different identities. Swap their source references while leaving the outgoing text unchanged. A validator concerned only with postal values will accept the substitution. The lineage gate should fail because evidence for one party cannot authorize a statement about another.

Gate 3: separate parsing from evidence

A parser proposes how text maps to fields. It does not automatically establish the truth of those fields. Consider a legacy address containing a building name, a district and a town separated inconsistently across lines. Several tokenizations may produce well-formed output. Choosing one requires evidence or an explicit uncertainty decision.

Classify each result by how it was obtained. Directly captured structured data, deterministic normalization, reference-data enrichment and human resolution have different failure modes. Keep those categories in the record. If a model proposes a country from surrounding text, record the proposal and its supporting input; do not silently upgrade the proposal to customer confirmed data.

A model confidence score can help prioritize review. It is not a substitute for source authority. Nor should a bank account's country, an intermediary bank's BIC, a browser locale or an IP location become evidence for a payment party's address without a justified, applicable business rule. These attributes describe different things.

The synthetic record below illustrates the shape of a decision. Its identifiers and versions are invented examples. It is an internal provenance envelope, not an ISO 20022 message or a complete production schema. The source's structured town and country were captured directly; no geographic inference is claimed.

{
  "decision_id": "address-decision-demo-42",
  "party_id": "party-demo-17",
  "payment_role": "creditor",
  "address_purpose": "registered_office",
  "source": {
    "record_ref": "evidence:beneficiary-demo-17",
    "revision": 8,
    "observed_at": "2026-09-24T04:00:00Z"
  },
  "fields": {
    "TwnNm": {
      "value": "Brussels",
      "source_path": "registered_address.town",
      "method": "direct_capture"
    },
    "Ctry": {
      "value": "BE",
      "source_path": "registered_address.country",
      "method": "direct_capture"
    }
  },
  "transform_version": "address-mapper-demo-3",
  "rule_profile": "bank-sandbox-hybrid-demo-2",
  "decision": "eligible_for_sandbox_serialization"
}

In a real envelope, also bind the exact source digest, the selected field values, the review identity when needed, and the full rule profile digest. Protect the record against unauthorized modification. An approval should refer to that exact combination. Editing a country after approval must invalidate the decision even if the record identifier stays the same.

Maintain an explicit list of unresolved fields and conflicting sources. A customer portal may disagree with an imported treasury file. The resolution policy should identify who can decide, which evidence they must inspect and how the correction propagates. Last writer wins is a concurrency strategy, not an address authority policy.

For teams outsourcing this boundary, Pharos Production's payment solutions development scope includes integration layers and ISO 20022 message parsers. Make field provenance and conflict handling explicit acceptance requirements when commissioning that work. A service description establishes relevant scope; it does not prove that a particular migration has passed these gates. Ask for one complete, anonymized decision walkthrough during acceptance. The reviewer should follow an individual field from collection through transformation and serialization, then see a failed case enter the correction process. That demonstration tests the promised boundary more directly than a presentation listing supported message formats.

Gate 4: version the scheme rules separately

ISO 20022 supplies a message vocabulary and structure. The actual payment flow also depends on its usage guidelines, market infrastructure rules, bank interface requirements and applicable release. Treating one schema validation result as complete approval collapses these layers and hides which requirement was checked.

Represent the applicable profile with at least the scheme or channel, message definition, guideline version, supported address representation and activation status. Retain the authoritative reference and the local approval that enabled the profile. Do not label an internal ruleset simply current: that name becomes meaningless when replaying an earlier decision.

Keep a distinction between a profile that is available in a sandbox, one approved for a bilateral test and one enabled for live traffic. A deferred industry release does not automatically disable a bank's existing support for structured addresses. It also does not authorize a local system to enforce future rejection rules across every route.

For each profile, specify the checks at their proper layer. Schema validation addresses structural conformance. Guideline validation checks the selected usage constraints. Business validation checks party applicability and the organization's accepted evidence policy. Route validation checks what the receiving connection actually supports.

Record separate outcomes so that a failed business rule cannot disappear inside a generic XML success flag.

When rules change, calculate the affected population from stored profile identifiers and field dependencies. Re-evaluate only decisions whose assumptions changed, while keeping their previous results available for investigation. A rule change affecting permissible address lines need not imply that every party identity must be recollected. A source authority change may require review even when the serialized message remains identical.

Keep historical reproduction separate from present eligibility. Reproduction asks whether the archived input, mapper and rules generate the recorded output. Present eligibility asks whether that address may be used now, under today's source state and active route policy. Store both answers with their own evaluation times. Re-running everything against the latest profile destroys the distinction and can make a previously valid decision look inexplicable.

For example, a reviewer may discover that a source country was corrected after a payment left the system. Preserve the earlier decision and attach the correction as new evidence. Investigate which subsequent payments inherited the old revision. The corrected value should not silently rewrite the historical message or imply that the earlier reviewer had information that arrived later. The migration calendar is itself a test case for this design. Archive the superseded activation assumption, attach the newer announcement and record who changed the operational profile. Historical decisions remain explainable without presenting an obsolete deadline as today's requirement.

Gate 5: prove that adapters preserve meaning

An address may be correctly structured in the customer database and still degrade before it reaches the payment message. A file export can concatenate fields. An integration gateway can truncate a line. A legacy API can omit a country field because its contract never carried one. Testing only the final serializer misses the earlier loss.

Map the actual route and compare the relevant values at its boundaries. Preserve field identity where possible rather than repeatedly flattening and reparsing text. If an interface requires a combined representation, document how structured values survive the transformation and what information cannot be recovered. Make loss visible before live release.

Use exact byte comparisons where the representation is meant to remain unchanged. Use defined semantic comparisons where an approved transformation changes encoding, case or ordering. The comparator's normalization policy needs its own version; otherwise a permissive comparison can conceal the same defect it was introduced to detect.

Build fixtures around the specific transformations your route performs. Include non-ASCII town names, long building identifiers, missing postcodes, multiple address lines and conflicting duplicate fields. Expected outcomes should come from the relevant profile and evidence policy. Do not treat every unfamiliar international address as invalid merely because it fails a domestic postcode pattern.

Pay particular attention to truncation and transliteration. If an adapter shortens a value, retain the pre-transformation value and a reasoned decision about whether the result remains usable. If the information cannot be preserved under the receiving interface's rules, send the case to remediation. A successful HTTP response is no evidence that a shortened address still identifies the intended location.

Attach the serialized message reference to the decision before transport, and correlate it with the transport acknowledgement or rejection afterward. Keep these states separate from settlement. A network acceptance says something about delivery or validation at that boundary; it does not establish the real-world accuracy of the customer's address or the final economic outcome of the payment.

Gate 6: rehearse exceptions and controlled replacement

The exception queue is part of the migration design. Give every stopped decision a machine-readable reason, an accountable owner, the affected party and a reference to the evidence that can resolve it. A free-text note saying bad address is insufficient for either automation or operational planning.

Separate unresolved evidence from technical delivery failures. An ambiguous town needs a data correction or an authorized resolution. A temporary transport failure needs the payment system's existing recovery procedure. Mixing these cases encourages operators to edit customer data to clear infrastructure errors, or to retry payments whose address decision was never approved.

A review action should create a new decision revision linked to the previous one. Preserve who changed which field, the supporting evidence and the reason. Require revalidation through every affected gate. If a source revision or ruleset changes while the item waits in the queue, invalidate the stale review rather than applying it to newer data.

Rehearse the following bounded scenarios in an isolated environment with synthetic records. The expected results are acceptance criteria for the proposed design, not reported measurements from a deployed bank system.

Injected condition	Expected control response
Town field exists but has no source mapping	Stop for missing field evidence
Correct values point to another party's record	Stop for party binding mismatch
Source revision changes after review	Invalidate approval and re-evaluate
Adapter silently drops a country field	Fail the boundary comparison
Profile activation is withdrawn before dispatch	Reassess eligibility under the active route policy
Operator corrects a rejected address	Create a new decision; retain the earlier evidence
Delivery result is unknown after a timeout	Investigate transport state before any payment resubmission

The last row prevents a dangerous category error. Replaying address transformation is a data operation. Releasing another payment instruction may create an additional financial obligation. The rehearsal must prove that a developer can reproduce the former without accidentally triggering the latter. Use a transport stub or disabled dispatch boundary and assert that no live send capability is available.

Roll back a defective mapper by selecting a previously approved software version for future evaluations, then review the affected decisions. Do not erase new source evidence to make an older mapper appear compatible. Messages already sent require investigation under the payment operation's procedures; changing a database value cannot retract them.

Measure the gaps that block release

A migration dashboard should distinguish capture coverage from demonstrated lineage. The proportion of records with town and country populated is useful, but it says nothing about whether those values came from defensible sources. Add measures for retrievable source revisions, valid party bindings, approved field decisions, adapter preservation and unresolved exceptions by route.

Define denominators explicitly. A party for which a postal address is not applicable should not inflate missing-address counts. An unused beneficiary record should not mask problems in the population scheduled for payment this week. Segment readiness by the actual source systems and routes that will be enabled together.

Track exception age and recurrence, including cases reopened after source or rule changes. Set operational thresholds using the team's demonstrated review capacity and the risk of the affected flow. Avoid selecting a universal target percentage without understanding which records remain outside it. One ambiguous high-impact route can matter more than a large volume of clean, inactive records.

Also inspect the reason distribution. A rising share of missing source references calls for an ingestion repair; repeated role mismatches call for a party model correction. Sending both populations to the same manual queue can conceal a systematic defect behind apparently productive review activity. Choose remediation at the boundary that caused the problem, then retain a small regression fixture showing why the correction was necessary.

Use the results to sequence rollout. Start with a bounded population whose source owner, message route and evidence lifecycle are understood. Expand only when the operational team can retrieve the evidence and resolve failures within its agreed process. The extension of an external deadline is an opportunity to fix weak capture boundaries, not evidence that the remaining data is ready.

The release packet a reviewer should receive

Deliver a compact manifest tying together the mapper version, source snapshot references, rule profiles, synthetic fixture results, adapter comparisons and exception procedures. Include the enabled routes and excluded populations. State which authoritative documents were checked and when, especially while release timing remains under consultation.

Ask a reviewer to select one passing record and one rejected record without help from the implementation author. They should be able to locate the relevant source revision, explain every structured field, identify the applicable profile and recover the message comparison. For the rejected record, they should identify exactly what evidence would permit a new decision.

Then change one dependency and repeat the exercise. A source correction should produce a traceable successor decision. A revised rule should explain which previous decision is no longer eligible. A replay should preserve the historical result while making today's assessment separately visible. If these distinctions cannot be recovered, adding more populated fields will not repair the migration.

Address migration is ready for controlled release when the team can explain how a particular address reached a particular message under a particular rule decision, and can stop or replace that decision when its evidence changes. That is the engineering capability worth building while the industry settles the next timetable.

About the author

Dmytro Nasyrov. Photo supplied by the author.

Smart Contract Engineering in 2026: Development, Audits, Upgrades and Release Evidence

Dmytro Nasyrov — Tue, 22 Sep 2026 21:52:33 +0000

A smart contract can pass its tests, receive an audit and still reach production with the wrong upgrade authority or an unreviewed initialization call. Each document may be accurate while describing a different version of the system. The release decision fails at the joins.

Smart contract engineering in 2026 needs a traceable connection between intended behavior, reviewed source, executable artifacts, administrative powers and observed deployment. This guide provides that connection: a route through six published technical articles, an evidence acceptance table and a release receipt you can adapt to your repository. The scope is Solidity and EVM systems. The year identifies this reading route, checked on September 23, 2026. It does not imply an industry survey or a universal security standard.

Choose the guide that answers your release question

Start with the decision you cannot currently defend. The following articles each contain a different working artifact. Reading them in publication order is unnecessary.

Your question	Guide and its specific job
What should a repository handoff contain?	Smart Contract Release Audit: 8 Repository Artifacts identifies the records to request before accepting delivery.
How do automated checks block a bad candidate?	Smart Contract CI/CD: Foundry, Slither, and Audit Gates connects build and analysis jobs to release gates.
Who can change the deployed system?	Smart Contract Upgrade Authority: Timelocks, Multisigs, and Emergency Controls maps normal and emergency administrative paths.
What happens if the new implementation fails?	How to Rehearse Smart-Contract Rollback Before Calling a System Upgradeable defines recovery exercises and the limits of code reversal.
How should I evaluate a development partner?	10 Smart Contract Development Companies Compared by Repository and Release Evidence in 2026 separates public evidence from project-specific delivery questions.
How do I test behavior across an upgrade?	Property-Based Testing for Upgradeable Smart Contracts: A Stateful Invariant Harness supplies a bounded teaching harness with handlers, ghost state and a deliberately broken upgrade.

Use the vendor comparison during selection, then move to repository acceptance when a team delivers your code. Public engineering activity can support a shortlist. It cannot establish that the people assigned to your project reviewed its economics, reproduced its build or rehearsed its deployment.

For a delivery organization offering blockchain software development, such as Pharos Production, this distinction matters at the handoff: service scope identifies the work offered, while the candidate's artifacts establish what was actually completed. Apply the same acceptance questions to an internal team and an external supplier.

Give every piece of evidence a subject

A filename such as final-audit.pdf is insufficient identification. Define the release subject using the repository and full commit, build configuration, dependency revisions, target chain and intended contract addresses. An upgrade also needs the currently deployed implementation and the candidate implementation. Keep intended values separate from observations read from the network.

The identity must extend beyond Solidity files. A deployment script can pass the wrong administrator without changing the implementation. Compiler settings can alter bytecode. An oracle address can change system behavior while every repository test remains unchanged. Include these inputs in the candidate and explain which checks cover them.

The following acceptance table is a proposed engineering policy. Adapt its owners and stop conditions to the actual system. It is not a report of completed checks.

Evidence	Acceptance question	What invalidates it?
Build record	Can the recorded inputs reproduce the intended artifact?	Source, compiler, dependencies or settings change.
Behavior results	Were the relevant properties exercised under declared assumptions?	Properties, handlers, configuration or relevant code change.
Audit disposition	Is the candidate inside the reviewed boundary?	An unclassified change crosses that boundary.
Authority snapshot	Do the actual accounts and roles match the approved model?	Owners, thresholds, modules, roles or delays change.
Recovery rehearsal	Does the procedure preserve the required state and access?	Migration logic, starting state or recovery powers change.
Deployment observation	Did the intended code and configuration reach this chain?	Wrong target, bytecode mismatch or insufficient confirmation.
Operations handoff	Can an assigned operator detect and handle the specified failure?	The monitored system or response ownership changes.

Release evidence joins candidate records to a chain observation. A changed input reopens its affected checks.

Do not replace this table with a weighted readiness score. A strong test suite cannot compensate for an unknown upgrade administrator. A documented exception needs its own scope, reason and authorized owner. An arithmetic average cannot accept it on their behalf.

Develop the behavior contract before the implementation

Write properties in business terms first. Which balances represent customer claims? When is a request irrevocably accepted? Who may mint, withdraw, cancel or change a limit? Which external data must be fresh? These answers define observable obligations that an implementation and its tests can share.

Consider a withdrawal queue. A useful specification distinguishes a requested withdrawal from a claimable one and a paid one. It says whether pausing new requests must preserve existing claims. It defines how rounding is allocated and whether a later parameter change applies to pending requests. Without these decisions, two correct-looking functions can disagree about the same liability.

Translate those obligations into contract boundaries, explicit permissions and testable state transitions. Keep an inventory of external assumptions: token transfer behavior, oracle updates, keeper availability and chain-specific execution conditions. An assumption belongs beside the property that depends on it, so a reviewer can see what a passing assertion leaves unresolved.

Pin the compiler and dependencies, and retain the settings used for the release. Check the selected compiler against Solidity's known-bug list, including the conditions under which a listed bug applies. A compiler version number alone cannot answer whether your settings and code encounter the issue. Record the review outcome with the build evidence.

Upgradeable contracts add initialization obligations. OpenZeppelin states:

“Do not leave an implementation contract uninitialized.”

OpenZeppelin, Writing Upgradeable Contracts.

The same guide describes locking the implementation with _disableInitializers and treating proxy initialization separately. Turn that distinction into explicit checks for each deployed address. The intended owner, initialized version and repeat-call behavior belong in the deployment review, not in an operator's memory.

Read test results as bounded evidence

A unit test checks a particular behavior. Fuzzing explores inputs within its configured domain. Stateful invariant testing explores sequences and asks whether a property survives them. These methods answer related questions, but their results should retain enough context to distinguish what actually ran.

For an upgrade, include behavior before the transition, the transition itself and behavior afterward. A fresh deployment of version two can pass every test while a populated version-one proxy fails during migration. Likewise, a successful upgrade transaction says little about whether old withdrawal claims remain redeemable.

The Foundry invariant-testing documentation explains sequence campaigns, handlers and configuration. Retain the tool version, selected profile, targeted operations, campaign bounds and failure reproduction data. Inspect successful calls and reverts as well as the final result. A handler that filters every difficult input may make an invariant easy to satisfy without exercising its intended risk.

Use a negative control when the property is important enough to gate release. Introduce a deliberate defect in an isolated test fixture and verify that the relevant assertion detects it. For example, a migration that resets an aggregate should fail the conservation property that compares aggregate and per-account obligations. Record that result as evidence about the test's sensitivity, not as proof that all migration defects are covered.

The linked stateful harness is a teaching example, not a production asset protocol. Adapting its structure requires replacing the model, actions and assumptions with your system's behavior. Copying its campaign settings or green result does not transfer its evidence to your release.

Keep static analysis alongside these tests. Preserve findings, reviewed suppressions and the analysis configuration. When a result disappears, determine whether code was fixed, coverage changed or a detector was disabled. The release owner needs the disposition, not just an empty findings panel.

Assign a question to every retained result. A conservation test might compare claims against assets under a defined token model. An authorization test should show that a forbidden actor cannot reach the protected state change. A liveness exercise should demonstrate progress under its stated assumptions about keepers and available liquidity. These are different obligations, so combining their totals into one test count hides information the reviewer needs.

When a test uses a fork, distinguish captured state from simulated future behavior. Record the fork block, dependency addresses and any substituted responses. A simulated oracle update or signer impersonation can be useful for isolating contract behavior, but it removes part of the operational problem. List that substitution so the release decision can require separate evidence for the real dependency or signing procedure.

Bind the audit to the release candidate

A smart contract audit has a scope: repository, revision, files, assumptions, exclusions and review method. Ask for those identifiers before treating its conclusions as relevant to a pending deployment. A report about the project can be authentic and still omit the migration you intend to execute tomorrow.

Create a finding-to-fix record. Each relevant finding should point to the remediation change, a regression check where appropriate, the follow-up review and any residual limitation. A team marking its own ticket closed is different evidence from the reviewer confirming the fix. Preserve that difference in the receipt.

Compare the audited revision with the candidate. Classify changes by affected behavior instead of accepting them because the diff is small. One address replacement can redirect authority. A single arithmetic adjustment can change claims. Documentation-only changes may need no new security review, but the classification itself should be visible and attributable.

This is also where delivery scope must become concrete. When development and audit handoffs lose the relationship between fixes and the deployable candidate, Pharos Production's smart contract development and audit preparation provides a relevant service scope spanning implementation, testing and security-review preparation. The acceptance record should still require evidence from the particular engagement. The service description does not establish an independent audit result.

Record accepted risks with the condition that made acceptance reasonable. If a limitation was accepted because withdrawals were capped, raising the cap should reopen the decision. Otherwise, a valid historical exception becomes an undocumented expansion of risk.

Review the complete upgrade authority path

Start at the function that can replace the implementation and work outward to every account or contract that can authorize it. Include powers that can change those permissions. A diagram showing a multisig at the top is incomplete if another role can replace the controlling administrator.

OpenZeppelin's access-control documentation describes ownership, role-based controls and timelocks. A threshold wallet distributes approval among signers. A timelock introduces delay for scheduled operations. Neither mechanism, by itself, establishes that the approved payload preserves user obligations. The control model must describe proposal, execution, cancellation and administration together.

Record the current threshold, owners, relevant modules and the roles on each controlled contract. Separate accounts allowed to propose a change from those able to execute or cancel it. Include changes to the delay itself. Read these values from the intended network at a recorded block. Deployment notes may describe an earlier configuration.

Then examine emergency powers. A pause role may block deposits while withdrawals remain available, or it may freeze both. An emergency upgrade path may bypass the ordinary delay. State the consequence explicitly and test unauthorized calls through each reachable entry point. A bypass justified for an incident remains a live administrative capability afterward.

Rehearse absence as well as compromise. Determine whether the required signers can actually act, whether a cancellation can arrive in time and who owns the response when one signer is unavailable. Do not choose a universal delay from a blog post. Its usefulness depends on detection, decision time, transaction inclusion and the actions users can take during the window.

Separate storage compatibility from recovery

A compatible storage layout is necessary for many proxy upgrades, but it cannot establish that the old implementation understands state written by the new one. A field can retain its type and slot while changing units, meaning or permitted values. Recovery must account for those semantic changes.

For example, suppose version one records a claim in whole units and version two migrates it into scaled units. Reverting the implementation pointer may succeed technically while causing version one to interpret the scaled value incorrectly. A rollback rehearsal must execute meaningful reads and transactions after reversal, rather than stopping at a successful administrative call.

OpenZeppelin's Foundry upgrade-validation API compares a new implementation against a declared reference. Preserve the reference identity and validation settings. A comparison against the wrong predecessor provides no useful answer about the proxy you operate.

Define the recovery strategy before approving migration: return to the old code where its state assumptions still hold, deploy a reviewed corrective implementation, or follow a bounded migration procedure. Document conditions that make each option unavailable. A pause can buy time while retaining state, but it does not reverse transfers or restore a previous storage snapshot.

Use representative populated state and retain the rehearsal's starting block or fixture. Include pending claims, active permissions and operations already in flight. Verify the obligations after recovery and the operator's ability to complete the next required action. If the procedure leaves the system permanently paused, explain how users regain access before calling the rehearsal successful.

Join the approved artifact to an observed deployment

Before signing, compare the full intended operation with the reviewed one: chain, target, value, calldata and administrative path. Decode parameters for the reviewer while retaining their exact encoded form. A familiar function name is insufficient when its arguments choose a different implementation or initialization recipient.

After execution, retain the transaction receipt and apply the confirmation or finality policy appropriate to the chain. Record the block number and block hash used for verification. A transaction accepted by a node is an earlier observation than a deployment accepted under that policy. Give these states separate names.

Compare deployed runtime code with the expected deployment artifact, accounting explicitly for linked libraries, immutable values and compiler metadata where relevant. Do not silently strip differences to obtain a match. Preserve the comparison method so another engineer can reproduce the result from the same build inputs.

For relevant proxy types, ERC-1967 specifies implementation, beacon and administrator storage slots and associated events. Inspect the mechanism the system actually uses. A beacon proxy adds a dependency through the beacon. A nonstandard proxy requires its own documented inspection path. An explorer badge does not replace this identification work.

Finally, check the initialized application state and authority configuration. Confirm the intended implementation, roles, limits and external dependencies. Where a check would create an irreversible effect, use a suitable simulation or a separately authorized bounded operation. Verification should not invent an unreviewed transaction merely to demonstrate that the deployment is alive.

Keep one receipt with explicit evidence states

The following YAML is an unfilled template, not an executable validator or a completed release. Every check begins at NOT_RUN. Null identifiers must be replaced with observed values. Copying the file cannot authorize a deployment.

schema: release-evidence-example/v1
candidate:
  repository: null
  source_commit: null
  build_input_sha256: null
  compiler_and_settings_ref: null
  dependency_lock_ref: null
target:
  chain_id: null
  proxy_address: null
  current_implementation: null
  candidate_implementation: null
  reviewed_operation_sha256: null
evidence:
  build: {status: NOT_RUN, artifact_ref: null}
  behavior: {status: NOT_RUN, artifact_ref: null}
  audit_scope_and_fixes: {status: NOT_RUN, artifact_ref: null}
  authority: {status: NOT_RUN, artifact_ref: null}
  recovery: {status: NOT_RUN, artifact_ref: null}
  deployment: {status: NOT_RUN, artifact_ref: null}
  operations: {status: NOT_RUN, artifact_ref: null}
observation:
  transaction_hash: null
  block_number: null
  block_hash: null
  finality_policy_ref: null
decision:
  status: NOT_READY
  reviewer: null
  accepted_exceptions_ref: null

Each referenced artifact should contain its subject identifiers, producer, observation time, result and limitations. Define a small state vocabulary: not run, passed, failed, invalidated and not applicable with a reason. Keep release authorization distinct from both a technical check and a transaction submission.

Retain a pre-submission decision and a separate post-deployment acceptance record. Deployment observations cannot exist before deployment, so an all-fields-passed rule would be circular. The first decision authorizes an exact operation after the required preparatory evidence is accepted. The second confirms what happened and whether operational ownership can transfer.

Hashing records helps detect changed bytes when a trusted comparison value exists. It does not prove that their claims are true or that their signer was authorized. Preserve review identity and artifact provenance alongside integrity values. Keep secrets and private signing material outside the evidence packet.

Make artifact references durable enough for an incident investigation. A temporary CI download link may expire before the next upgrade. Retain the relevant build inputs, reports and replay instructions in an access-controlled archive with the release identifier. Test whether the receiving engineer can retrieve the packet using their own access, rather than relying on the original author's workstation or browser session.

Treat configuration changes as releases with their own scope

A new implementation is only one way to alter a smart contract system. An oracle replacement, a fee adjustment or a role transfer can change user outcomes without changing runtime bytecode. Give such changes an exact subject and acceptance path instead of exempting them because no compiler ran.

For a parameter update, record its old and proposed values, permitted bounds and affected obligations. Determine how it applies to already accepted work. A fee update may be valid for new requests while breaking the economics of a pending queue if applied retroactively. The required evidence should follow that behavior change. Rebuilding unchanged code is not a substitute for reviewing the parameter's effect.

For a dependency replacement, establish the interface and failure behavior your application relies on. The same function signature does not guarantee equivalent units, freshness, permissions or revert behavior. Preserve the chosen address and the assumptions checked against it, then update monitoring to observe the replacement. Treat a change to those assumptions as a reason to revisit the dependent properties.

For an authority transfer, verify that the recipient can exercise its intended role and that the previous principal has only the powers the plan allows. Some transitions require an acceptance step. The receipt should distinguish transfer requested from transfer completed and should identify the observation that resolves the distinction.

Scope the work proportionately. A configuration-only release can reuse unchanged build evidence while requiring new parameter, authority or operational checks. A code upgrade may require the whole path. The useful question is which dependency changed and which conclusion relied on it. Write that relationship down before selecting the checks, then preserve the rejected and superseded records so the history explains why a new decision was necessary.

Walk a candidate through rejection and acceptance

Imagine a hypothetical upgrade with passing behavior tests and an audit covering its source commit. During deployment preparation, the operator changes the migration recipient. The source tests remain green, but the reviewed operation no longer matches. The receipt should invalidate the operation review and any rehearsal dependent on that recipient.

The fix is to review the changed parameter, rerun affected checks and issue a new decision for the exact payload. Unaffected evidence can remain valid if its dependencies are unchanged and that conclusion is recorded. This avoids both careless reuse and an expensive ritual of rerunning everything without asking what changed.

Now suppose deployment succeeds but the observed administrator differs from the approved configuration. Record the actual state and keep operational acceptance blocked. Diagnose the mismatch and use the authorized incident or correction procedure. Never edit the expected value after execution merely to make the comparison pass.

Operations should receive alerts tied to the same model: implementation or role changes, violated accounting properties, stale dependencies and failures of required off-chain services. Every alert needs a destination, an accountable responder and an available action. A notification without authority to respond leaves the handoff unfinished.

The release is ready for operational acceptance when the approved candidate, observed chain state and assigned response process agree within their documented limits. Keep the receipt with the release, reopen affected decisions when inputs change, and use the linked specialist guide for the next missing piece of evidence.

About the author

Dmytro Nasyrov. Photo supplied by the author.

GitHub Release to Zenodo DOI

Dmytro Nasyrov — Thu, 17 Sep 2026 07:21:09 +0000

Cover illustration: evolving source becomes one preserved release.

A GitHub release can exist before its Zenodo archive is ready. A DOI can resolve while the metadata still misrepresents the files. A discovery service can list the record without having checked whether the software works. Treating those events as one success state makes a release difficult to reproduce and surprisingly easy to describe incorrectly.

This guide follows a real software release through those boundaries. The example is version 1.1.0 of an LLM-as-a-judge cost calculator, published on August 16, 2026. Its GitHub release, archived files, DOI resolution, DataCite metadata, OAI-PMH response and OpenAIRE entry were checked again on September 17. The useful deliverable is a small verification receipt that tells the next developer exactly what was preserved and what each check established.

Start with the object someone will cite

The calculator release is a browser application with calculation code, tests, methodology and dated pricing registries. That combination gives another developer something to inspect and reuse. A repository containing only an announcement would offer much less reason to preserve a particular version.

The release work behind Pharos Production software development supplies the concrete example here: a cost model packaged with explicit assumptions and separate terms for code and data. The engineering problem is retaining the inputs behind an estimate when the application and vendor prices later change. Archiving a named release preserves those inputs; it does not keep them current.

The identities checked for this example are:

Object	Observed identifier	What it identifies
GitHub release	`v1.1.0`	The named release and its notes
Git commit	`67b6d1d9d741214a986ea4d7ce7111a99605bbf3`	The source revision resolved from that tag
Zenodo record	`21963489`	The published archive and its metadata
Version DOI	`10.5281/zenodo.21963489`	This particular archived version
Concept DOI	`10.5281/zenodo.21963488`	The work across its versions

On the verification date, the public Zenodo record contained one ZIP file of 133,258 bytes. Its advertised MD5 checksum matched the downloaded archive. The four citation and license files inside that ZIP also matched their counterparts at the pinned Git commit byte for byte. This is a bounded file comparison, not a claim that every executable path was retested for this article.

Record the commit separately from the tag. In this case GitHub's release response reported immutable: false; the existence of a release URL alone therefore did not establish GitHub release immutability. The version DOI and retained archive checksum provide different evidence from a mutable repository page.

Complete preflight before enabling automatic deposits

Choose the smallest package that supports independent use. Include source, installation or execution instructions, dependency information, representative tests and the data needed for the documented example. If a benchmark depends on a private dataset that cannot be shared, say what remains unavailable and how that limits reproduction.

Check the actual archive contents, particularly when a project uses generated binaries, submodules, large files or separately hosted assets. A successful source-code archive does not by itself show that every resource mentioned in the README was deposited. The calculator example has no uploaded GitHub release assets; its archived ZIP is the object inspected here.

For reproduction, preserve the invocation as well as the program. A calculator result needs its workload values; a benchmark needs its configuration and measurement procedure. A DOI pointing to the right code does not tell a reader which options produced a reported number. Put those inputs in a small example or run manifest, with expected outputs and tolerances where relevant. If an external service is required, document that dependency and the resulting limits. A source archive can preserve an algorithm while leaving the environment needed to execute it only partly reproducible.

Confirm that publishing every included file is intended. Remove secrets, private configuration, customer records and accidental build outputs before tagging. Decide authorship from contributions rather than copying whoever happens to operate the release account. Verify the creator's name, affiliation and ORCID against the intended citation, and retain that decision with the release review.

GitHub's official guidance states:

“Make sure to include a license in your repository so readers know how they can reuse your work.”

GitHub, Referencing and citing content.

That instruction belongs in preflight because an archive cannot repair missing permission by assigning an identifier. A useful review asks which files are covered by each license, where the applicable terms are stored and whether third-party materials have separate conditions. A repository-level badge is too coarse for a package containing differently licensed components.

For the integration itself, GitHub documents public-repository access and notes that an organization owner may need to approve the Zenodo application. Review that access deliberately. Then use Zenodo's GitHub settings to synchronize the repository list and enable the intended repository. Do not interpret a successful account connection as evidence that the correct repository is enabled. The enable-repository guide describes these as separate steps.

Give citation metadata one clear owner

Keep CITATION.cff in the repository root when you want GitHub to offer a citation through its interface. It describes the software for people and citation tools. The example's archived file includes the title, version, author, ORCID, repository URL and a description of its two license scopes.

Zenodo also accepts .zenodo.json. Its current metadata documentation makes the precedence explicit: when both files exist, the GitHub archiving integration uses .zenodo.json and ignores CITATION.cff. It does not merge them. A corrected author in CFF cannot compensate for a stale creator in the JSON file.

Choose an owner for each repeated field. For example, a release review can require title, version and creators to agree across the two files, while reserving Zenodo-specific related identifiers for JSON. This is a proposed consistency check, not a claim that either service enforces your repository's policy automatically.

A short excerpt from the actual archived JSON shows why reviewing fields individually matters:

{
  "version": "1.1.0",
  "upload_type": "software",
  "access_right": "open",
  "license": "other-open",
  "language": "eng"
}

This is an excerpt, not a complete upload template. In particular, other-open describes the historical release input; it is not a recommendation to replace specific license declarations with a generic value. The full file contains creators, description, keywords, related identifiers and notes defining the code/data boundary.

Validate the exact files contained in the tag. Checking only the default branch after publication can inspect a later correction that never entered the archive. JSON syntax validation catches malformed JSON, but it does not prove that an identifier, relationship or license choice is appropriate. Review the supported fields and then inspect the resulting record.

The same distinction applies to CFF validation. Schema validation and correct citation intent are separate checks. A well-formed file can still point to the wrong software version or credit an unrelated paper. Keep the intended citation in the review so a mechanically valid result can be compared with it.

Choose a version DOI for reproducible claims

Zenodo's DOI versioning explanation distinguishes a specific version from the concept representing all versions. The first publication creates both identifiers; later versions receive their own version identifiers. The relationships belong in metadata rather than in an invented suffix appended to the DOI.

Use the version DOI when a result depends on the exact software or data you used. A cost estimate based on the calculator's August pricing registry should identify that release, its workload inputs and the registry's verification date. A general project description may instead refer to the concept DOI because its subject is the evolving work.

Both identifiers resolved to record 21963489 during this check. That shared destination does not make their meanings interchangeable. It only describes their resolution at the time of observation. A receipt should store both identifiers with explicit field names, rather than a single ambiguous doi field copied from whichever badge was easiest to find.

Likewise, keep release version, publication date and data-verification date separate. Version 1.1.0 was published on August 16; its pricing sources were described as verified on August 13. Neither date makes those prices current in September. This article verifies the preserved object and its metadata, not today's commercial pricing.

The LLM observability cost methodology explains the problem the calculator addresses: different billing entities require explicit workload assumptions. Keeping that methodological context beside the versioned artifact helps a reader understand an estimate. The company article remains contextual documentation, not independent validation of the software.

Preserve mixed licenses across representations

The example assigns MIT to source code and the static application. Its DATA-LICENSE.md assigns CC BY 4.0 to normalized pricing records in data/ and docs/data/. Those paths matter: two license names without file scope could be misread as offering a choice of terms for every file.

Zenodo's license guidance permits declaring multiple licenses for mixed uploads. Keep the file-level explanation inside the archive as well as in record metadata. A downloaded ZIP should remain understandable without requiring the reader to reconstruct an earlier state of its landing page.

The September inspection exposed three different representations of the same release. The archived JSON retained other-open. The current legacy Zenodo Records API exposed a single MIT license object plus descriptive notes. DataCite's rightsList and the OAI-PMH response each included MIT and CC BY 4.0. The public record's metadata had therefore evolved beyond the original release input.

This is why reading only metadata.license.id would have produced an incomplete account. A consumer using that field alone could miss the data license even though it was present in other exports and in the archive. Compare the rights arrays, human-readable notes and actual license files before declaring that the metadata lost or preserved every condition.

Do not generalize this observation into a promise that the integration automatically reconstructs mixed licensing. The evidence establishes the archived input and the current published outputs. It does not establish that every intermediate transformation was automatic. Keep any post-publication metadata correction in the release history so later maintainers can explain the difference.

A practical review assigns a row to each materially different file group: paths, copyright holder or attribution, license file and exported license identifier. If a component's rights are unclear, resolve that uncertainty before depositing it. Adding a second identifier to metadata is not a substitute for permission to distribute a file.

Publish once, then reconcile the integration result

Prepare the release from the reviewed commit, confirm the intended tag and publish through the normal GitHub release workflow. Enabling the repository is preparation; creating the GitHub release triggers the integration. A tag pushed by itself should not be treated as evidence that this documented release workflow completed.

Zenodo's archiving guide explicitly includes a processing interval. Wait for the integration result, open the resulting record and compare it with the intended release. The existence of a GitHub release page is only the first observation in this sequence.

Use separate operational states: release published, ingestion pending, record published, DOI resolved and metadata verified. Store a timestamp and evidence URL for each completed state. These are suggested states for your own release process; they are not a list of status names returned by every service.

When ingestion reports a metadata error, inspect the error for that exact release. Correct the responsible metadata before deciding on a new release. When the result is merely unknown because a request timed out, first look for an existing matching record. Repeating publication immediately can create another object without resolving the uncertainty about the first attempt.

Keep a retry decision tied to repository, tag and resolved commit. A background worker should never interpret an empty response as unconditional permission to make a fresh deposit. Record the unresolved state and the next read-only reconciliation step. This also helps a human maintainer resume after an interrupted browser session without guessing which actions occurred.

For CI, put preflight checks before release creation and verification after it. A read-only verification job can fail without creating a second release. Keep publication credentials out of the verifier; reading the public evidence below does not require them. That separation gives reviewers a useful tool without handing every verification run authority to publish.

Each box requires its own observation. A successful archive does not certify software correctness or completion in every downstream service.

Verify the archive and the exported metadata

The following Python 3 script makes a bounded set of public, read-only requests. Run it in an empty directory: it saves four response snapshots and the archive for inspection. It does not execute downloaded software, create a deposit, modify permissions or require a token. Any failed request or assertion stops the check.

import hashlib
import json
from pathlib import Path
from urllib.request import urlopen
import xml.etree.ElementTree as ET

DOI = "10.5281/zenodo.21963489"
RECORD = "21963489"

def read(url, filename):
    with urlopen(url, timeout=30) as response:
        payload = response.read()
    Path(filename).write_bytes(payload)
    return payload

record = json.loads(read(
    f"https://zenodo.org/api/records/{RECORD}", "record.json"))
assert record["doi"] == DOI
assert record["metadata"]["version"] == "1.1.0"
assert record["status"] == "published"

files = record["files"]
assert len(files) == 1  # Expected for this particular release.
archive = read(files[0]["links"]["self"], "release.zip")
assert len(archive) == files[0]["size"]
assert "md5:" + hashlib.md5(archive).hexdigest() == files[0]["checksum"]

attributes = json.loads(read(
    f"https://api.datacite.org/dois/{DOI}", "datacite.json"
))["data"]["attributes"]
assert attributes["doi"] == DOI
assert attributes["state"] == "findable"
assert attributes["version"] == "1.1.0"
rights = {x.get("rightsIdentifier") for x in attributes["rightsList"]}
assert {"mit", "cc-by-4.0"} <= rights

oai = ET.fromstring(read(
    "https://zenodo.org/oai2d?verb=GetRecord&metadataPrefix=oai_dc"
    f"&identifier=oai:zenodo.org:{RECORD}", "oai.xml"))
ns = {"o": "http://www.openarchives.org/OAI/2.0/"}
assert oai.find("o:error", ns) is None
assert oai.findtext(".//o:header/o:identifier", namespaces=ns) == (
    f"oai:zenodo.org:{RECORD}")

openaire = json.loads(read(
    f"https://api.openaire.eu/search/software?doi={DOI}&format=json",
    "openaire.json"))
assert int(openaire["response"]["header"]["total"]["$"]) == 1
print("Archive SHA-256:", hashlib.sha256(archive).hexdigest())
print("Bounded checks passed; inspect the saved metadata and match identity.")

The script's expected record, version, file count and two rights identifiers are deliberately specific. Change those expectations only after reviewing a different release. Weakening the assertions until an unrelated record passes would remove the reason to run the check.

The observed archive SHA-256 was 3e72a12ee4ef08095bd57e35c92ef061fe995b153cd15251bfedcb870ae30655. Keep that digest with the timestamp and original download URL. The service-provided MD5 is useful for checking a completed download against its record; the separately retained SHA-256 supplies a stronger content fingerprint. Neither digest establishes who authored the code or whether it is correct.

Read each verification result at its actual scope

DataCite's public API exposes findable DOI metadata. For this release it returned the expected creator, version, both rights declarations and an IsVersionOf relationship to the concept DOI. Those checks establish registered, discoverable metadata with the expected fields. They do not establish peer review or successful software execution.

OAI-PMH answers another question: can a harvester retrieve this repository record in the requested metadata format? The saved GetRecord response contained the expected OAI identifier, title, DOI and both rights declarations. Inspect the XML body as well as HTTP status, because a protocol-level error can still arrive in a successful HTTP response.

The OpenAIRE software query returned one matching result. Its title, creator, original OAI identifier and landing-page URL matched the example. Its returned status included UNDER_CURATION; the article therefore claims observed discovery, not completed curation. A result count alone would be insufficient without those identity comparisons.

The script checks that count but leaves the richer OpenAIRE identity comparison visible in the saved response. In a maintained verifier, make the expected identifier and landing URL explicit assertions too. Avoid a title-only comparison: titles can change, be reused or appear on related records.

Software Heritage is a further boundary. The Zenodo API response contained an empty swh object during this inspection, so completed Software Heritage preservation was not established. Keep that result unconfirmed rather than promoting it to success because the DOI resolves. A later verified archival identifier can update that particular observation.

These services provide useful persistence and discovery infrastructure. Their presence in a release record should not be presented as endorsement by CERN, a security audit, a license-compatibility opinion or a guarantee of search traffic. State exactly which response was inspected and what matched.

Make a failed check actionable

A verifier should distinguish a content mismatch from an unavailable observation. If the downloaded archive has the wrong checksum, stop treating that download as the expected object. Preserve the response details and compare the advertised file identity before investigating further. Do not replace the expected checksum with the newly observed value simply to restore a passing result.

If a public API returns an access error, timeout or rate limit, record the affected service and leave its observation unresolved. That result does not prove the record was removed. It also does not establish that the previous successful response still describes current metadata. Retain the last verified snapshot with its original timestamp and keep the fresh failure separate.

If DataCite resolves the expected DOI but shows an unexpected creator or rights list, classify the problem as a metadata mismatch. Inspect the published Zenodo metadata and the corresponding export before editing repository files. Changing the current branch cannot retroactively change which bytes were archived in the existing ZIP, so it may be the wrong repair for the observed defect.

If OpenAIRE returns no matching result while the record and DOI are available, report that particular discovery check as unconfirmed. Choose a bounded later recheck appropriate to the release process. Do not claim a guaranteed indexing delay or create another deposit to make a search result appear. Discovery latency and archive identity require different responses.

These branches deserve a simple responsibility map. A release maintainer owns the tag and package contents. A metadata reviewer owns creator, relationship and rights corrections. A verifier records observations and can block acceptance, but should not invent an alternative publication when a downstream service is unavailable. A small project can assign all three responsibilities to one person while still keeping their decisions distinct.

Preserve enough context for another operator to diagnose a failure: request URL, UTC time, response status, expected identity and the comparison that failed. Avoid putting tokens or private account responses into a public receipt. The example uses public endpoints, so its relevant evidence can be shared without exposing publication credentials.

Finally, a successful rerun should append a new observation. It should not erase the failed attempt or turn its timestamp into the time of eventual success. That history explains whether the release was initially wrong, temporarily unavailable or waiting for another service. It also prevents an incident review from confusing a later repair with what readers could access at publication time.

Correct metadata without disguising a new release

A misspelled creator or incomplete description is a metadata correction. Zenodo's record-management guidance permits published metadata to be edited without changing the DOI. Preserve the previous and corrected values, the reason and the verification timestamp, especially when downstream exports are part of the acceptance criteria.

Changes to calculation logic or pricing files create a different reproducibility object. Use the version-management workflow for substantive file changes, then cite the new version when reporting results produced with it. Keep the old version identifiable for people who used its earlier behavior.

Avoid an absolute claim that published files can never change. The current file-management documentation describes a limited correction window: minor file edits can be initiated within 30 days, with the draft published within 45 days of the original publication. Outside that window, justified exceptional cases go through support. That exception makes a retained archive digest worthwhile even when a DOI is stable.

For this calculator, a new vendor price or formula changes the inputs behind an estimate and should be reviewed as a new version, not silently described as the old reproducible result. Updating an explanatory sentence about license scope is a different operation. Classify the change by what a reader would need to reproduce, then preserve the corresponding history.

Finish with a release receipt someone else can use

Keep the final receipt small: repository, tag, commit, record URL, version DOI, concept DOI, archive filename and digest, expected creators, license scopes, check timestamps and unresolved observations. Link each conclusion to the response or file that supports it. A green job badge without these identities is weak evidence for a later investigation.

Accept the release when the intended archive is retrievable, its metadata describes the right work and the version citation resolves correctly. Report downstream discovery separately, including pending or unconfirmed services. This leaves the next maintainer with a precise starting point: a preserved object, a readable citation and a documented boundary around what was actually verified.

About the author

Dmytro Nasyrov. Photo supplied by the author.

DEV Community: Dmytro Nasyrov

Sportsbook iFrame Integration: Test Reconnects Against the Original Wallet Operation

Give the session and the operation different lifetimes

Lose the reply after retaining the wallet decision

Recover a result through a read

A retained rejection must survive a changed balance

Keep unknown results unresolved

Run the same contract against both implementations

Complete runtime: fake wallet and both reconnect implementations

Complete unchanged test suite

Connect the model to an actual iframe boundary

Make the acceptance record useful to another team

More insights to read

About the author

Separate Request IDs From Operation IDs in an Integration Retry Test

Specify what each identifier is allowed to mean

Put the operation record beside the protected effect

Lose the response after the commit

Run the same assertions before changing the client

Move operation identity outside the attempt boundary

Read the six passing contracts precisely

Adapt the contract at the next system boundary

Keep an executable acceptance packet

More insights to read

About the author

Regulated Tokenization Engineering in 2026: Identity, Transfer Controls and Auditability

Start with the instrument and the accountable owner

Define the evidence contract before designing the dashboard

Treat identity as a changing relationship

Choose enforcement boundaries, then choose a standard

Audit exceptional authority as its own product behavior

Rehearse a revocation while settlement is pending

Build auditability around history and reconciliation

Invalidate evidence when dependencies change

Make the handover answer a disputed transfer

More insights to read

About the author

Top 5 Token Transfer-Control Architectures for Regulated Assets Compared

Compare the decision boundary first

1. Pharos Production: Token Transfer-Control Architecture with Embedded Rules

2. External Identity and Compliance Registries

3. Signed Transfer Certificates

4. Partition-Scoped Transfer Policy

5. Agreement-Ledger Authorization

Walk One Revocation Through All Five Designs

Give Emergency Paths Their Own Policy

Make the Selection Reviewable

More insights to read

About the author

ERC-3643 vs ERC-1400: How to Choose a Standard for Tokenized Instruments

Start with the instrument, not the token number

Compare a final specification with a standards family

ERC-3643 makes investor eligibility an explicit dependency

ERC-1400 partitions expose which balance is moving

Use disqualifiers before assigning scores

Walk one holding through both models

Preflight is a snapshot, not a settlement promise

Administrative paths need their own contract

Integration includes settlement and document state

Require a reproducible selection record

More insights to read

About the author

Omnibus vs Segregated Wallets: The Ledger Decides

Separate the wallet, the ledger and the authority

Compare the evidence each model needs

A balanced total can hide the wrong allocation

Run the snapshot witness and the regression

Reservations and withdrawals need a posting policy

Preserve identities through deposits and sweeps

Signing authority does not replace reconciliation

Make the acceptance receipt reconstructable

Choose the promise you can keep

More insights to read

About the author

How to Implement ERC-3643 Transfer Controls for Permissioned Tokens

Start with a policy-to-operation map

Pin the contracts before interpreting the standard

Make identity requirements explicit

Implement one recipient-country module

Route configuration through the compliance owner