shared

func RecordAddress ¶

func RecordAddress(ab cldf.AddressBook, ds datastore.MutableDataStore, chainSelector uint64, address string, tv cldf.TypeAndVersion, qualifier string) error

RecordAddress writes one contract address to both the legacy address book and the datastore, deriving identical metadata from one TypeAndVersion so the two stores cannot drift. The datastore AddressRef copies the address-book labels (token symbol, token address) so the state loader reconstructs the same TypeAndVersion without RPC.

Writes are ordered so a failure touches as little as possible: the datastore key is checked read-only first, then the address book is written (idempotently), then the datastore. The datastore write uses Add, not Upsert: within one changeset run, writing one key twice with different addresses is always a bug — Upsert would drop the first ref and report success, leaving a contract on chain that the registry never mentions. Conflicts with rows written by *previous* runs cannot be seen here (the datastore passed in is the changeset's own output store) — those are checked upfront by ValidatePlannedRefs, before anything is deployed.

func TokenQualifier ¶

func TokenQualifier(symbol string) string

TokenQualifier returns the datastore qualifier for a token-scoped type: the canonical token symbol. Operator input can carry display-name spacing ("CCIP BnM"); the qualifier uses the symbol form ("CCIP-BnM") so Aptos rows key identically to the EVM, Solana and Sui rows for the same token. Normalising here rather than at each call site keeps the two spellings from producing two datastore keys.

func ValidatePlannedRefs ¶

func ValidatePlannedRefs(env cldf.Environment, replaceExisting bool, planned []PlannedRef) error

ValidatePlannedRefs checks that the refs a changeset is about to write can be recorded in the datastore, and is meant to be called from VerifyPreconditions before any transaction is signed or staged. A conflict caught there costs a re-run; the same conflict discovered during Apply means the contracts are already deployed on chain, and since a changeset that fails mid-way returns an empty ChangesetOutput, every address it had recorded up to that point is discarded too.

It reports every problem it finds:

• a multi-instance ref with no qualifier, which would collide with its siblings;
• two planned refs sharing one datastore key;
• a planned key already taken in the environment, where recording the new address would silently replace the existing one (MemoryDataStore.Merge upserts).

An occupied key is an error unless replaceExisting says the caller means to take it. That intent has to be stated rather than inferred: the two cases are indistinguishable from the datastore's side, and the framework resolves them identically and silently. When the caller opts in, each displaced address is logged.

Callers must declare only the refs they will actually deploy on this run, mirroring the conditionals in Apply, so that an existing key always means a genuine conflict.

Two things this cannot see, both structural. It compares against the environment datastore as it stands before the changeset runs, so it will not catch two changesets in the same pipeline claiming one key that collision only materialises when their outputs are merged. And on a chain whose datastore is empty the check is vacuous: rows recorded under an earlier qualifier scheme occupy different keys, so the re-qualification tooling owns retiring them.