返回文章列表
chainscardano-reference-input-configuration-lifecycle
⛓️

How to Replace a Cardano Reference Input Without Losing Track of Its Readers

A Cardano configuration cutover uses reference inputs, explicit version identity, and retiring outputs to make reader behavior predictable.

iBuidl Research2026-11-1817 min 阅读

TL;DR A Cardano reference input lets a transaction inspect an existing unspent output without consuming it. That makes shared configuration readable by many independent transactions, but spending the old output still ends its usefulness to newly validated readers. Plan a configuration change around exact output references, validity of the application policy, observed ledger state, and the builders that need time to move.

A catalog copy arrives at the wrong desk

A fictional cooperative called Basin issues digital practice permits for a simulated workshop. Its Cardano design needs an approved catalog of permit types. Each permit purchase consumes a user-controlled funding input and can read the catalog to learn the applicable terms. The cooperative wants to update the catalog occasionally without routing every customer purchase through a single mutable account. The basic design seems promising until the first replacement, when some pending purchases still point at the old publication.

Basin's maintainer can explain the disagreement in two sentences. A build made yesterday refers to an actual transaction output. A catalog application running today displays a different output as its current publication. Which purchase will actually validate depends on what the purchase refers to, which output is still unspent, and the explicit application policy. A builder cannot make the reference point at a different publication by changing its display.

This cutover guide uses labels A and B for two imaginary catalog outputs. An output reference is normally a transaction identifier and an output index. The labels stand in for complete references in all decisions that follow. Basin retains both full values in a release record to avoid asking a human to infer the configuration from a shared address or an explorer's timestamp sorting. The fictional system's timing and costs illustrate design choices rather than claims about any live protocol.

A configuration is readable in two senses. An off-chain application can render old bytes from an archived output and reassure its user that the proposed action was assembled under version A. A new transaction carrying A as a reference input requires that the referenced output actually be available when the ledger validates it. A catalog search screen can satisfy the first meaning even after spending ends the second. The release procedure has to maintain both paths if someone must explain an old accepted purchase after the migration.

Sheet one. What the transaction brings to the ledger

Cardano's ledger represents spendable funds and associated data in unspent transaction outputs, or UTxOs. CIP-31 adds reference inputs. The referenced output must exist in the UTxO set. Its value does not fund the candidate transaction, its spending conditions do not need to be met just for reading, and it is not removed by a validated transaction that only references it. An application script can see the reference through an appropriate script context. A normal spending input still supplies the different action of consuming its output. CIP-31 reference inputs

A reader is therefore a normal transaction with enough spending inputs to pay for its own activity. Basin's purchase may read words from A while paying with an unrelated customer input. The ADA sitting on A remains attached to A. A wallet whose preview totals both values would mistakenly suggest that money could be spent just because it was visible. A useful transaction review shows which outputs are being consumed and which outputs are present to supply data, then computes the actual balance from the spendable side.

Data availability requires another deliberate decision. A referenced output can carry an inline datum under CIP-32. That means the datum is attached to the output instead of requiring a builder to obtain the data behind a hash separately when it needs those bytes. A datum hash still identifies an expected value but does not by itself hand readers the value. If Basin elects to use hashes it needs a way to supply the corresponding datum to consumers who depend on it. The distinction comes up again when an old endpoint loses its cached metadata. CIP-32 inline datums

CIP-33 addresses reference scripts. A ledger output can carry a script that an appropriate transaction can reference instead of transmitting the full script as a witness in the usual way supported by that mechanism. Basin chooses an independent lifecycle for any shared script artifact and for its frequently changed configuration. If they reside on the same output, the retirement decision removes both kinds of reference at once. The two objects can be combined intentionally, but the consumers should know why they have one retirement date. CIP-33 reference scripts

Compatibility belongs in this sheet even if most users run a current app. CIP-31 describes version boundaries for scripts whose context cannot represent reference inputs. An application may have existing spending paths that are deliberately kept compatible with older validators. Basin tests the composed transaction and its actual script versions before assuming that a new reference input may be added to every order. A builder that only shows a success preview can conceal a validation boundary until the signed transaction reaches the ledger.

Sheet two. A label gains authority through a rule

Basin's old presentation layer chooses the last catalog object returned by its provider. That is a convenient display policy during a demo. The ledger still needs a precise rule about what counts as an approved configuration. A reference input simply supplies a particular UTxO. The protocol operation does not approve every object visible at an ordinary address or decide which current catalog Basin's application means. A project defines the authority for its publications and checks the evidence appropriate to its contract.

The cooperative has an approved set of publication records. A reader expecting A can describe the exact authorized reference and the application version that understands it. The release process introduces B under an explicit authorization policy. It chooses which record resolves current version and whether there will be a period when both approved versions can be used for some actions. The policy may rely on exact identities, an authenticated marker, or another mechanism suited to the design. Each choice should be tested inside the authority boundary it claims to enforce.

The maintainer writes down three independent axes. First comes byte format. Can the reading code decode the datum and understand its version? Second comes publication identity. Can the reader establish that the datum came from an approved configuration output? Third comes applicability. Do the product rules allow that version for this purchase at this point? A well-formed datum can be inapplicable. A previously allowed version can be unsupported by a new decoder. Tying the three decisions to one number would make it harder to explain a rejection.

Basin tests a currentness disagreement without treating it as an attack. One regional service intentionally caches catalog A and the other obtains B. Both see plausible old and new output references. The business requirement says a known set of already quoted purchases may finish on A during a limited overlap, and unquoted new purchases should use B. The validator enforces whatever applicability conditions the product says the chain controls. User interface hints handle convenience. Relying on every front end to quietly stop building against A would leave the enforceable part of the policy unclear.

The review also covers source-of-truth disputes. A project website says that an update is live at noon. At noon a participant has still not observed the publication on its selected chain view. The website's statement may express an operator's intent. It supplies no unspent output reference on its own. A wallet can say that the configuration was announced or that it has confirmed the configuration is available as separate status values. A release runbook that names both kinds of entry makes them straightforward to communicate.

Sheet three. Four candidates cross the cutover

Candidate one uses A before publication of B. It carries an allowed reference and spends independent customer inputs. The result proceeds under the old terms when the rest of the validation holds. Keeping an exact acceptance record here prevents a surprise later if the historical display comes from the latest catalog service. The fulfilled order should remain explainable under the configuration on which it actually relied.

Candidate two uses A during the planned overlap. Output B has appeared and A remains unspent. The hypothetical policy allows this specific existing quote to finish with A. The transaction carries the appropriate inputs and evidence for that policy. A ledger reader can show that B existed without asserting that every transaction of that window had to use it. The cooperative wants overlap to be a deliberate product choice. It should have test cases for allowed and disallowed uses inside the same interval.

Candidate three uses B after a builder refresh. The builder obtains the approved new reference, decodes its datum, and forms the new transaction. The user can see any change that affects the real terms of the purchase. Amounts, permitted activities, or destination might be different. The signature for a message built under A cannot authorize a materially different B transaction. Even if the visible terms exactly match, the signed content includes changed inputs. The rebuild step is the right place to obtain current approval.

Candidate four still uses A after A has been spent. The transaction references something that no longer exists in the UTxO set of the validating view. An old indexer page can display the stored A datum, while the candidate no longer has the available reference it needs. This version must be rebuilt or an explicit alternative applied. The failure message should tell the customer that configuration changed during preparation and preserve any distinction between an unsigned draft, a signed attempt, and a transaction that was actually accepted.

There is an additional race inside the fourth candidate. Imagine a legitimate A reader and A's authorized retirement both pending in the same environment. A reader processed before the retirement can still have access to an unspent A if its application policy allows. A reader processed afterward cannot use A through the reference mechanism. The cooperative tests both orderings with controlled fixtures. Knowing when the transactions were submitted helps debug the run, but validation order and state decide its outcome.

Two B readers can overlap without consuming B. This removes one source of contention that existed when every transaction had to spend and replace the configuration output. Other shared spending inputs still serialize some activity. Two purchases that both spend the same inventory output remain in contention even if their catalog references are ideal. A throughput review therefore maps all spending and referencing dependencies rather than attributing every conflict or improvement to the configuration feature.

Sheet four. Stale discovery and rollback need a response

Basin's eligible publisher submits B at its scheduled change time. An indexer reports B and shortly afterward loses part of its chain feed. A second endpoint can see A and no approved B in its view. The program can't safely resolve this simply by preferring the letter farther through the alphabet. It needs to know the evidence level required by the application's publication procedure and what the operator should do while readers disagree. A client can decline to build a new purchase until it can verify the relevant configuration and explain that delay.

One discipline makes this process easier. The deployment plan names the view under which a publication becomes available for building. This can include the observed chain reference and the confirmation practice adopted for that application. A dynamic search for the newest row becomes a checked lookup for the intended publication. If the view changes, the client can invalidate cached drafts pointing to the uncertain output. It can also compare the draft and refresh results before soliciting a replacement signature.

A rehearsal starts with a healthy index, advances the ledger, then freezes one reader's data feed. The test checks whether the builder displays the provenance of its configuration. Another fixture publishes B but deliberately withholds the data that one client requires to decode it. The client's fallback should follow the allowed applicability policy. If there is no allowed fallback, a clear pause is preferable to a locally invented catalog. Returning a cached human-readable price does not resolve missing chain evidence or schema support.

Closing a release uses a similar distinction. An authorized operator may be able to retire an output when the application no longer needs it, including recovering value under its spending conditions. Retiring a shared reference while some pending users still need it creates downtime for those buyers. Keeping all old outputs indefinitely ties up funds or storage and complicates version governance. Basin compares the continuing operational obligations of overlap, the quantity of value committed in old outputs, and the permissions needed to spend the retired publication.

A simple invented comparison gives the operations team something to discuss. Three old versions each hold two units of funding that remain locked while the outputs stay active. Retiring two releases makes four units available under the team's fictional spending arrangement. The numbers do not express actual minimum ADA or fees. They show why the owner should know who benefits from retaining each old reference. If one retained publication supports an outstanding contractual quote, measuring the cost without that obligation would promote the wrong version.

A failback also needs a usable old reference or a new publication. Once A was spent in the accepted view, documenting that Basin administratively chose A's terms again does not put the old output back. A publisher may create a new authorized output with those terms under a procedure its readers understand. That output has a new reference even if all the data bytes match the old catalog. This difference lets staff explain why a prior signature and a restored policy are still separate records.

The release owner tests the retirement decision against real queues

A large team might consider a new version deployed once its own builder points at B. Basin has two builder versions and three ways people receive a quote. A public kit still contains a pinned A reference. A hosted service discovers authorized publications dynamically. A kiosk gets its configuration at the start of an activity and remains offline for part of the session. These readers place different demands on the overlap. If the operator relies only on the hosted service for telemetry, its successful calls can hide the other two devices.

The evidence plan lists each supported reader and records its last feasible A submission. One case follows a kiosk that was explicitly told it can honor existing quotes for an hour after opening. Another records how the pinned kit will communicate the need to upgrade. Those requirements can be expressed as product constraints before the project chooses a release date. Defining an overlap after the old output is already gone cannot protect the signatures people already gave.

The team distinguishes a test that proves an old quote may still finish from a test that proves a customer can recover after it no longer can. In the first, the existing authorized A reader receives the result that was promised under its configuration. In the second, a failed A attempt causes the client to request current terms, then seek approval if appropriate. A serious discrepancy such as a price increase has a separate user-visible outcome. The application should preserve enough information to show why the terms changed during rebuilding.

A small dry run reports installed versions by reader. Imagine 12 hosted clients and 3 kiosks in a practice environment. All 12 hosted clients now obtain B, while 2 kiosks report that a session is still pinned to A. Writing adoption as 12 out of 12 would be accurate for the hosted service and incomplete for retirement. Basin's owner records both denominators and checks whether the kiosk sessions still qualify to finish before spending the old output. This is why the maintenance review uses affected builds or open commitments, depending on the question, in place of one undifferentiated deployment percentage.

The owner also specifies how to stop a problematic migration. If B remains readable but the new catalog is found to contain a business error, the publication team can halt new B work under the application's intended authority and investigate. Replacing B's visible profile in a web dashboard alone does not change the datum at its existing output. The corrective operation must designate the intended version through the application's actual rules. The team archives the faulty publication alongside its approval, acceptance observations, and the correction, so old transactions can still be explained.

A maintainer reads a snapshot from last winter

Consider the purchaser asking in six months why the accepted price differed from the current price. Basin's archive has the original signed business reference, the transaction result, and the catalog datum that applied when it was accepted. The old output may have been consumed. The ability to retrieve and interpret a historical record doesn't require leaving the output unspent forever. It does require retaining enough data to explain the transaction and identifying how the reference was proved at the time.

One maintenance task follows directly. The archive cannot depend wholly on a provider query that returns only today's UTxOs. That query may be ideal for building a new transaction. A historical support request may need retained chain history or an independent approved archive. Basin's docs name the source used for each job and who owns it. If old hashed datum bytes remain meaningful after retirement, someone must keep the associated value and explain how it connects to the relevant publication.

Another task is to make the catalog durable across old and new application versions. The format record states how unknown fields are handled and whether two versions encode the same business promise differently. An older viewer that cannot interpret a new field can show the historical amount and identify the unsupported detail without guessing. An upgrade test pairs an accepted old purchase with the new support screen. A budget for account verification and readable support is part of the migration, even though the actual UTxO operation fits in a short specification.

The design has a further practical consequence for permissions. Updating authenticated configuration and spending user payments are operations with different decision makers. Basin models them independently. An update can be approved through configuration governance, while a purchase still requires the user's appropriate approval and its normal spending conditions. Separating those records keeps a revision review focused on what changed in the catalog and an order review focused on how the customer's funds actually moved.

Basin's final cutover document has enough specificity for a reader to know which complete reference is currently usable, which preexisting candidates the overlap supports, and how to rebuild after retirement. It records both the intended transition and the state observed at release. Seeing the current catalog is a lookup. Correctly using it is a transaction design decision with an exact chain dependency. The publication record becomes valuable because the operator can trace that dependency from construction to validation and preserve its meaning after the change.

Sources

更多文章