Repository navigation
sRFC 41: Solana Clear Sign Meta-Intents Extension #12
Replies: 2 comments
|
Genuine question on scope: does the meta-intents model envision flows where a delegated party (e.g. an autonomous agent operating within a user-signed policy or budget) submits transactions on the user's behalf, and the user later sees a clear-signed summary of what the agent did? If so, has the working group thought about distinguishing "user-directly-signed" vs "agent-acted-within-prior-authorisation" in the meta-intent payload? Agent payment flows are starting to land on Solana (x402, agent-side escrow patterns) and the trust signal at the wallet UI layer there is non-trivial. Happy to share a concrete example if useful. |
|
Two points on the attested account state that the safety rules depend on, and a smaller note.
Many signing devices have no trusted clock, so one option is for the source to sign over the hash of the message under review, or over a device challenge, plus the slot it read at. Each attestation then belongs to one transaction. With a recent blockhash its age is bounded by the blockhash window. A durable-nonce transaction has no such bound, so it would need the challenge or an explicit slot limit. sRFC 39 notes that RPC providers can serve fabricated account states, but there that state feeds display metadata. Here an attested figure decides whether a movement is folded into another one, so the line that the extension "adds no trust assumptions of its own" may need a sentence on this.
A smaller note: even a fresh read describes its slot, not the slot the transaction lands in. A sentence on that window may help. Douglas |
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
This document extends sRFC 39: Solana Clear Sign with cross-instruction value-flow tracing and transaction-level intent reduction.
Motivation
sRFC 39 covers how each instruction is displayed: field formatting, intent strings and skip rules. It says nothing about how to render a transaction as a whole.
A Solana transaction is a flat list of instructions, and most of them are scaffolding around what the user actually wants to do, like wrapping SOL or closing a token account. For multi-instruction transactions, sRFC 39 can only join the per-instruction intents with
"and", which gives strings like:The user's actual intent is:
This extension defines how a wallet can get back to that intent from the raw instruction list: it traces value as it flows from one instruction to the next, then reduces the result to the smallest form the user needs to see.
Summary of additions
srfc41.valueFlowplugin oninstructionNodemintAssociationNode,ownerAssociationNodehideConditionsNode(createdInTransaction,isSigner,accountUsedElsewhere,accountEffectsDisplayedElsewhere, …)Design principles
Every node introduced here is optional. An IDL without them is still a valid sRFC 39 document and renders with the base behavior. Wallets that don't implement the merge stage fall back to per-instruction interpolation, and wallets without interpolation fall back to field lists.
The merge engine has no concept of instruction categories. How and in which direction instructions merge depends only on the ports each instruction declares.
Merge and hide only change what is displayed. They have no effect on consensus, and the transaction signed on-chain is always the full instruction list. A wallet implementing this extension MUST offer an opt-in raw view (see Advanced-User Display).
Overview
Each transaction goes through four stages: Annotate → Merge → Hide → Render. Every instruction's
srfc41.valueFlowpayload resolves to the same shape,inputs[(account, amount, token)]/outputs[(account, amount, token)]. The merge engine then joins, collapses and filters these triples down to a minimal set of intents for the user.Pipeline walkthrough
The example below follows a typical Jupiter swap, where 7 raw instructions become a single displayed intent.
1. Annotate
The IDL declares the value each instruction consumes and produces as
(account, amount, token)triples.balanceis symbolic: it drains or fills whatever the account currently holds. Annotation also keeps track of mint and owner associations declared withmintAssociationNodeandownerAssociationNode, so that ephemeral token accounts can be resolved to a mint and an owner. A declaration only applies to the instructions after the one that declares it, never to earlier ones (see Association order and conflicts).2. Merge
The engine goes left to right and fuses an item with a later one when its outputs match that item's inputs through a shared account.
Transfer sends SOL into
wsol_ata, SyncNative turns it into WSOL, and Route swaps the WSOL for USDC. The three collapse into a single Swap.CreateIdempotentandCloseAccountcan't be merged in, so they move on to step 3.3. Hide
The remaining lifecycle instructions are checked against their
hideConditionsNoderules. An instruction is hidden only if every condition in a rule set holds.Every instruction in the wrap, swap and unwrap chain touches
wsol_ata, soaccountUsedElsewhereholds. The owner and the destination both belong to the signer, soisSignerholds too.4. Render
The display nodes on each argument's type scale the raw amounts, and the surviving instruction's
interpolatedIntentbuilds the final string.The next section defines the merge rules precisely. Worked Example 1 goes through the same swap again using those rules. The other examples cover native staking, multi-hop routing and flash-fill orders.
Merge Algorithm
The merge stage has three steps:
accountResetNodedeclarations of all items into the set used by the symbolic junction guard.The rest of this section describes the scan in detail.
Concepts
Glossary
inputs[(addr, amount, token)],outputs[(addr, amount, token)].balanceAmountNode(drain or fill of the full account balance). Not numerically comparable.kdon't have agreeing token identity (two different mints, or an Unknown on either leg), or (b)len(inputs) ≠ len(outputs)(asymmetric ports: a sink or a source), or (c) some portkhasinputs[k].valueKind ≠ outputs[k].valueKind(both non-empty). An Absent leg agrees with anything, so on its own it never makes a pair a transformation.len(inputs) == len(outputs)) whose port amounts are all symbolic. It changes the form of the value (for example lamports to WSOL) without declaring any concrete amount.len(A.outputs) == len(B.inputs),A.outputs[k].account == B.inputs[k].accountfor everyk, every port pair has a compatiblevalueKind, and every port pair has agreeing token identity.native,splTokenandconfidentialare all compatible with each other, since they all match by address. Compatible kinds alone are not enough for a match: the token identities must agree too.len(C.inputs) == len(C.outputs). This applies to both rules, and the merge is blocked if it fails.Token identity
A port's token identity is what it says about the asset it moves. It is always one of four states, and the merge relies on telling the last two apart:
fixedTokenNodewithsymbol: "native", which everyvalueKind: "native"port MUST declare. Lamports count as wrapped SOL, so the identity is the mintSo11111111111111111111111111111111111111112, even though the descriptor names no mint.valueKind.nullTokenNode(or no token node) on a port that moves no value, meaning a numeric amount of0. This is the creation marker used byCreateATAand similar instructions.nullTokenNodeon a port that does move value, or a symbolic amount with no token.Two ports have agreeing token identity if and only if at least one of them is Absent, or both are Mint/Native with the same mint. An Unknown agrees with nothing, not even another Unknown.
The engine uses these four states the same way everywhere it asks what a leg carries, and an Unknown always results in an extra screen:
accountEffectsDisplayedElsewhere, it counts as an effect that nothing covers.How merging works
Items are processed left to right. For each item A that has outputs, the engine looks forward for the first item B whose inputs match A's outputs position by position (see Account match above). When it finds one, it assigns the S and C roles and fires a rule. The rule consumes C and propagates
C.farsideintoS.junction.The junction and the far side are defined from C's point of view:
C = B, thenC.junction = C.inputs,C.farside = C.outputs, andS.junction = S.outputs.C = A, thenC.junction = C.outputs,C.farside = C.inputs, andS.junction = S.inputs.Each port pair
(A.outputs[k], B.inputs[k])is classified on its own, and all pairs must land on the same rule. If they don't, the merge is blocked.An item with an unresolved port amount (for example a
confidentialAmountNodethat wasn't decrypted) can't be merged: it can neither consume nor be consumed. It can still stop a forward scan early if it references one of A's output accounts.Rules
Rule table
AAS.junction[k].account ← C.farside[k].accountS.junction[k].account ← C.farside[k].accountS.junction[k].amount ← C.farside[k].amount(numeric, equal)← C.farside[k].amountif numeric, else keepS.junction[k].amountS.junction[k].valueKind ← C.farside[k].valueKindS.junction[k].amountS.junction[k].token ← C.farside[k].token← C.farside[k].tokenif non-null, else keepS.junction[k].tokenSurvivor assignment
Before trying to match ports at all, both items must pass the positional integrity check. Every step below reads ports by position, and an item that lost a declared port to exclusion can't be read that way.
Once ports match, the engine picks S and C before evaluating the rule:
{A, B}a value transformer?Steps 5 and 6 come after role assignment because they depend on the role, not on the pair: the same two instructions might be able to merge with the roles swapped.
Per-rule details
Rule 1 (numeric chain): both items agree on the exact numeric amount at the junction, so all four fields (account, amount,
valueKindand token) are copied from C's far leg without conditions. This includes a far leg that is symbolic, which is why the far leg still has to be bounded before the collapse can happen. Agreeing at the junction only tells you something about the junction, not about the far side.Rule 2 (symbolic junction): when at least one side of the junction is symbolic, each field is propagated separately, with a safe fallback:
balance, andbalanceis never replaced by an unrelated number.valueKind: always follows the amount. The side that supplied the merged port's amount also supplies itsvalueKind. If S kept its own figure, it keeps its own kind.nullTokenNodefrom a creation step has no token identity.When both sides are symbolic, the default
C = Ameans the instruction that runs last survives, as with Rule 1.If S or C has a symbolic junction amount, or C's far side has one, the Symbolic Junction Guard must also pass.
Guards and edge cases
Symbolic Junction Guard
This guard applies to any merge that would leave a symbolic leg on S, either at the junction or through propagation, so it is evaluated under both rules. All three checks below must pass. They are evaluated over every account on which either item holds a symbolic leg, and each of those accounts is checked against the instructions holding those legs.
A collapse affects more than the two legs facing each other. It also points S's junction leg at C's far leg, so that S names the real counterparty instead of the intermediate account the value went through. A symbolic leg picked up this way ends up in the review just like a junction leg would. Two legs agreeing on a number settle the junction, but they say nothing about the far leg that gets copied over, which is why an exact relay also goes through this guard. The guard may find nothing to check only when nothing in the whole collapse is symbolic. It is not enough that nothing is symbolic where the two instructions meet.
Safe-account check. The junction account must be in the transaction's safe-account set, which is built from
accountResetNodedeclarations. Being in the set guarantees a known balance: zero ifresetValueis omitted, otherwise the resolvedresetValue. A reset whose declaredresetValuedidn't resolve guarantees nothing, and per Balance domains it isn't in the set in the first place.resetScopeon a safe-set entry is evaluated against the instruction that owns the symbolic leg on the account, which is not necessarily the consumed side. Each checked account lists every item that holds a symbolic leg on it (S, C or both), and the account passes only if each of those items is matched by at least one of the account's entries.setTokenLedgerpattern below to collapse, since the numeric fill feeding its junction comes from a program the scope excludes. The only case where C is still tested over a numeric junction leg is check 3, when a symbolic leg on C's far side brings that junction under scrutiny. S is never tested for a leg it didn't declare.dtakes effect afterdruns (seeaccountResetNode), so the entry covers no leg of the collapse ifdcomes after the earlier of S and C. For a symbolic input leg on C's far side whenC = A, it only applies ifdcomes strictly before C.Fully-accounted depositor check. Every instruction that comes before the later of S and C in transaction order and lists the junction account as writable in its raw account list must be S, C, or an instruction already merged into S or C. This ensures every write to the junction can be traced back to the merge chain, whether or not the intermediate instruction declares a value-flow output on the junction.
accountResetNodefor the junction account is exempt, since its write is the reset that sets the known balance. "Applicable" means the same thing as in check 1: a reset whoseresetScopematches none of the account's leg owners, or that isn't in effect yet when the leg is read, covers nothing here and doesn't exempt anyone either.Unbounded-propagation check. Every symbolic port on C's far side must be bounded before S can take it over. Which account has to pass checks 1 and 2 depends on the direction, because each direction is bounded by a different fact:
C = A, the far side isA.inputs, and each symbolic leg there must pass checks 1 and 2 for its own account, not only for the junction.C = B, the far side isB.outputs, which is fed by the junction C drains. So the leg that has to pass checks 1 and 2 is the junction leg paired with it (B.inputs[k]), with C as its owner for scope evaluation. A symbolic junction leg is already checked in its own right, so this happens automatically. A numeric one is not.Checks 1 and 2 bound the junction balance, and therefore a symbolic drain of the junction: the drain reads exactly what this chain deposited. They tell you nothing about a symbolic fill of the junction, because there the value moves in the other direction. When
C = A, C's junction-side ports fill the junction and its far-side ports drain another account, so a reset on the junction doesn't limit what C moved. Rule 2 still keeps S's concrete figure and puts C's far-side account on it, so without this check the review would show a small fixed amount for what is actually a movement of that account's entire balance.When
C = B, the far side is bounded by the junction feeding it. A junction leg with a number doesn't add a leg to check, so checks 1 and 2 never ran on the junction and nothing established what it holds. A number on the junction leg doesn't bound the far leg either: by design, C's two legs don't have to balance, so an amount coming in from the junction says nothing about a whole balance leaving on the other side. Once the junction is held to checks 1 and 2, the bound is real, and forwarding everything the chain put there moves exactly that amount.If any check fails, no merge happens. See Symbolic Balance Merge Safety for the reasoning.
Creation-marker survivor guard
A junction can't be classified when every leg on the survivor's side is a creation marker, that is a
literalAmountNodewithvalue: 0and either anullTokenNodeor no token node.A creation marker says that an account was created empty. It shows a creation without adding any value to the chain. That's why it is the only literal amount that renderability accepts: it has no figure, so there is nothing to lose. But for the same reason it can't be a survivor. Both rules copy
C.farside[k].accountontoS.junction[k], so a creation marker that survives would end up showing a recipient in its only field, a field that means the account that was created. The merged item would then show a destination under a label that means something else.Refusing the junction costs the user nothing: the consumed instruction stays a separate item, shown with its own descriptor and hidden only by its own conditions.
Intent-less removal
Items with a recognized descriptor that resolve to
inputs=[],outputs=[]and nointentare removed. They have no value flow and mean nothing to the user (account initialization is a typical example).Removal happens after the safe-account set is built and the merge scan has run, not before. An intent-less item is invisible to the user, but it still runs on chain, so the merge guards must still see it:
accountResetNodedeclarations still go into the safe-account set. A reset describes the chain state after the instruction runs, and that stays true whether or not the instruction is shown.The ordering makes no difference the other way round. An intent-less item has no ports, and both merge rules need a matching port on each side, so the scan can't consume such an item or let it consume another one. It can only block a merge, never take over a survivor's display.
intentbut no value flow stay visible (Stake:Deactivate,Stake:Authorizeand similar).inputs=[], outputs=[]as nothing the user needs to see, which is only true when the engine decided the ports were inactive. When it couldn't decide, an empty port list means something wasn't read, not that nothing happens.When no rule fires
If the amounts differ, the junction token identities don't agree, or the consumed symmetry invariant fails, no merge happens and both items stay visible. The engine never collapses instructions it can't classify, and that includes a junction where a port has no token identity at all: an unknown blocks the collapse instead of allowing it.
Display source selection
The merged result is always displayed with the survivor's sRFC 39 display definition. Since the transformer is made S during Survivor Assignment, there is no need for a separate way to choose the display source. The merge only replaces runtime values (account addresses and amounts) used by S's display template.
A value that isn't used by any field of that template isn't displayed at all. The merge has no screen of its own: it fills in S's fields, and a port that doesn't match one of them is just not shown. So binding a port to a field is a requirement on the descriptor, and an engine can't assume it (see Port amount renderability).
Algorithmic properties
Transfer -> SyncNative -> Swap, the consumedSyncNativewrites the junction it was folded into and must not stopTransferfrom reachingSwap, but an instruction folded away by an unrelated merge must stop it.Transfer → SyncNative → Swap, Transfer absorbs SyncNative with Rule 2 and then matches Swap.IDL Extension Schema
Everything in this section is optional. An IDL without it is still a valid Codama document and renders with the base interpolation and fallback behavior.
Carrier
Version 1 of this document put
valueFlowinsideinstructionDisplayNode, which broke the IDL.instructionDisplayNodeis a closed interface that only hasintent?andinterpolatedIntent?, so the extra key made the IDL non-conformant, and a regular Codama visitor silently drops it. There is no error or warning: the value flow disappears the first time the tree is transformed.So the payload now uses Codama's official extension point,
instructionNode.plugins[]:{ "kind": "instructionNode", "name": "swap", "display": { "kind": "instructionDisplayNode", "intent": "Swap", "interpolatedIntent": "Swap ${data.inAmount} for at least ${data.quotedOutAmount}" }, "plugins": [ { "kind": "pluginNode", "name": "srfc41.valueFlow", "payload": { "version": 2, "inputs": [ ... ], "outputs": [ ... ], "accountResets": [ ... ], "mintAssociation": { ... }, "ownerAssociation": { ... }, "hideConditions": { ... } } } ] }version2for this document. Codama doesn't version plugin payloads, so the payload carries its own versioninputsvalueFlowPortNode: value consumedoutputsvalueFlowPortNode: value producedaccountResetsaccountResetNode: accounts created or resetmintAssociationmintAssociationNodefor instructions that create token accountsownerAssociationownerAssociationNodebinding a token account to an ownerhideConditionshideConditionsNodefor post-merge lifecycle hidingPayload references are not maintained by Codama
Codama never walks into a payload, never validates it, and doesn't keep identifier references inside it up to date when the tree is transformed. If Codama renames something, it updates every node it models, but every reference in this payload keeps pointing at the old name.
valueFlowPortNode.account,argumentAmountNode.argument,mintAssociationNode.account/.mint,ownerAssociationNode,accountResetNode.accountandhideConditionRuleNode.targetare all references to names in the IDL, made from inside that payload. An implementation loading these descriptors MUST check each of them against the base IDL and MUST treat a dangling reference as a hard failure. An outdated account name doesn't cause a visible error at render time. It resolves to nothing, the port silently disappears, and the merge shows the user paying less than they really do.Path grammar
This payload uses dotted paths (
inAmount,params.quotedOutAmount). Codama'sinterpolatedIntentuses a different syntax (${data.x}/${accounts.x}, flat after the root), and the two are not interchangeable. The flat-after-root rule only applies to the interpolated sentence. Payloads are opaque to Codama, so this extension can keep its more expressive paths.An instruction that declares any port MUST declare a non-empty
intent. The two go together: an emptyintentis how a descriptor says the instruction means nothing to the user, and intent-less removal only drops such an instruction if it also has no ports. A descriptor with an emptyintentand a port contradicts itself, and there is no safe way to interpret it:intentto render.Implementations MUST reject such a descriptor when loading it, instead of trying to resolve the contradiction at display time. An instruction that really moves no value declares no ports and is removed. An instruction that moves value declares an
intentand is displayed or merged.The reverse also applies: an instruction with an empty
intentSHOULD declare nothing except itsaccountResets. Display fields describe a screen it will never reach, andhideConditionsapply to a survivor it will never become, because intent-less removal drops it before the hide stage runs. OnlyaccountResetNodestill matters, because the safe-account set is built before removal. Constrained signers MAY reject the other parts on such an instruction instead of transferring and storing data nothing will read.valueFlowPortNode
Each port describes one leg of a value movement: which account, how much, and which token.
{ "kind": "valueFlowPortNode", "valueKind": "splToken", "account": "source", "amount": { "kind": "argumentAmountNode", "argument": "amount" }, "token": { "kind": "accountMintTokenNode" } }kind"valueFlowPortNode"valueKindaccountaccounts[]), or an ordered array of such names resolved to the first provided candidate (see Account resolution)optionalAccountStrategyaccountis an array. Selects how an unset optional candidate is encoded:"programId"(default) or"omitted"(see Account resolution)amounttokenactiveWhenvalueKindsemantics:valueKindnativefixedTokenNode: "native"splTokenconfidentialAn amount only means something together with its kind. Lamports and the base units of a six-decimal token are both raw integers, but the same integer in each doesn't represent the same value. So whenever the merge moves an amount, its
valueKindmoves with it (see Per-rule details).Ports should not reference protocol-internal accounts, like vaults, reserves or pool accounts, that mean nothing in the user's value flow. For example, a flash-loan borrow from an order reserve to the taker should only declare an output on the taker's account, not an input on the reserve. If such accounts are declared, the merge carries them along the chain and the user ends up seeing internal plumbing instead of what they are actually doing.
Renderable port amounts
A port's
amountMUST be renderable by the instruction that declares it. For every port whoseamountis anargumentAmountNodeor aconfidentialAmountNode, the argument at that path MUST resolve to anumberTypeNodewhosedisplay.kindisamountNumberDisplayNode, looking through anyoptionTypeNode,sizePrefixTypeNodeorfixedSizeTypeNodewrapper and through anydefinedTypeLinkNode. A type at that path with a different display node, or with none, doesn't meet the requirement, because an amount is only substituted into a field that displays amounts.The rule has three details that the version-1 rule either got wrong or didn't address:
structFieldDisplayNode, but what marks a value as an amount is on the type.u64inside anoptionTypeNodeis still the number holding the amount. A check that stops at the wrapper reports a false failure, and an author might then "fix" it by moving a display node onto the wrapper, where Codama doesn't model one, so it silently disappears.amountNumberDisplayNodethat comes from the program's own IDL counts exactly like one added by an overlay. The check reads the merged tree. A check that only read the curator's overlay would force curators to repeat what upstream already says, and a curation layer must not require that.A chain-resolved amount meets the requirement, by design, with an
amountNumberDisplayNodethat has nodecimalsand nounit. The scale comes from a two-hop chain carried by a plugin, and the node's presence is what marks the value as an amount. A consumer that only understands Codama renders the raw value under a clear label, which is the intended fallback.The same reasoning decides the other amount nodes:
balanceAmountNodeis exempt. It has no figure to lose, and what a merge may keep or propagate over it is handled by the Symbolic Junction Guard. The exemption only holds because that guard covers every symbolic leg a collapse can move, both at the junction and on the far side, and under both rules. If the guard were limited to the junction pair, the exemption would no longer hold: a whole-balance leg could then reach a survivor with no bound and no field required to render it.literalAmountNodeis accepted only withvalue: 0, the creation marker. A literal isn't addressed by an argument path, so no field can ever receive it.value: 0is safe because it has no figure and neither rule can give it one.This requirement is what makes amount propagation visible. A merge moves the consumed item's amount onto the survivor's port, and the only way that figure reaches the screen is through the field that reads the same path. If a port isn't bound to such a field, the collapse silently loses the very amount it was supposed to carry.
The requirement only depends on the instruction, so it is checked once, when descriptors are curated:
Account resolution
accountis usually a single account name. It MAY instead be an ordered array of names, for ports whose real source or recipient is an optional account that replaces a default slot. The engine tries the candidates from left to right and resolves the port to the first account that is provided. Every later step (matching, merge, hide, guards) works on that resolved address, so nothing else changes.A candidate is provided when its account slot holds a real account. How an unset optional candidate is encoded is set by the port's
optionalAccountStrategy, which only matters whenaccountis an array:optionalAccountStrategy"programId"(default)"omitted"The last candidate MUST be a non-optional account, so that resolution always succeeds. The earlier candidates are the optional overrides, from most to least specific.
Token resolution nodes
Token resolution nodes identify the asset being moved. They are used both to match value chains and for display.
fixedTokenNodesymbol: string"native"for lamports (which resolves to the wrapped-SOL mint as a token identity)accountMintTokenNodeaccount?: stringfallbackAccount?: stringtoken_balances[address of account].mint, whereaccountdefaults to the port's own account. Falls back to address offallbackAccountif absentnullTokenNodeaccountnames the account whose mint is read, which isn't always the port's own account. For example, aToken:CloseAccountoutput port is on the lamport recipient but must carry the token identity of the account being closed, so it names that account explicitly.accountandfallbackAccountrefer to different kinds of account. The table above says so, but it is easy to miss.accountis a token account, and what is read is its on-chain.mint.fallbackAccountis the mint itself, used by its address ("falls back to address offallbackAccount"). The difference is intentional, because the two cover different cases: in one, the mint has to be read from the token account's own data, and in the other the instruction already names the mint. An implementation that treats them the same resolves the wrong account without any error. This mistake occurs in practice, and a typical symptom is a provenance line reportingdestinationMint.mint.decimals, one hop too far, for a descriptor that is actually correct.Examples:
{"kind": "fixedTokenNode", "symbol": "native"} {"kind": "fixedTokenNode", "symbol": "So11111111111111111111111111111111111111112"} {"kind": "accountMintTokenNode"} {"kind": "accountMintTokenNode", "fallbackAccount": "sourceMint"} {"kind": "accountMintTokenNode", "account": "account"}Amount resolution nodes
Amount resolution nodes give the quantity being moved.
argumentAmountNodeargument: stringargumentis a dotted path (see below)balanceAmountNodeliteralAmountNodevalue: integervalue: 0means creation with no valueconfidentialAmountNodeargument: stringDotted paths: each
.-separated segment ofargumentgoes one level down into nestedstructTypeNodefields. For example,"args.amountIn"readsamountInfrom a struct argument. If a path doesn't resolve, the amount is unresolved and the item can't be merged. The same goes for aconfidentialAmountNodewhen decryption fails or the key isn't available.Typical usage:
argumentAmountNode: Transfer ("lamports"), Swap ("inAmount").balanceAmountNode:CloseAccount,SyncNative,Delegate.literalAmountNode:CreateATA.Port activation
A port can declare
activeWhen, an array of predicates evaluated during annotation. If any predicate fails, the port is excluded and the instruction has no leg there.Evaluation model
Activation is decided in a single stage, before merge and hide. It goes through the instructions in transaction order, and through each instruction's ports in the order they are declared. Once decided, activation is never recomputed.
Two rules keep the result well defined:
activeWhencan never be read as active.Changing the order of instructions can change activation, and that is expected. Instruction order is part of the signed message and of what the runtime executes, so two orderings of the same instructions are two different transactions, not two ways of rendering the same one. In particular,
createdInTransactionmeans nothing for a creation that hasn't happened yet: an instruction moving value into an account created later in the same transaction fails on chain, so a predicate returningtruethere would describe a state that never happens.A predicate is either a string identifier from the condition vocabulary (shared with
hideConditionsNode) or a structured object:mintPredicatemint: stringExample:
CloseAccountports that are only active for WSOL. The input port reads the mint of its own account. The output port is on the lamport recipient, so it names the closed account in order to carry the same token identity.{ "kind": "valueFlowPortNode", "account": "account", "amount": {"kind": "balanceAmountNode"}, "token": {"kind": "accountMintTokenNode"}, "activeWhen": [{"kind": "mintPredicate", "mint": "So11111111111111111111111111111111111111112"}] } { "kind": "valueFlowPortNode", "account": "destination", "amount": {"kind": "balanceAmountNode"}, "token": {"kind": "accountMintTokenNode", "account": "account"}, "activeWhen": [{"kind": "mintPredicate", "mint": "So11111111111111111111111111111111111111112"}] }For any other mint the ports are excluded and
CloseAccounthasinputs=[], outputs=[]. The instruction is then either treated as infrastructure or stays visible as an intent-only item withintent: "Close". This only applies when the engine actually read the mint and it wasn't wrapped SOL. If it couldn't read the mint at all, the same two ports are excluded because of an unresolved predicate, and the instruction stays visible.Unresolved predicates
Every predicate needs some input.
mintPredicatereads the port's token, the condition-vocabulary predicates read the port's account, and one of them also reads other ports.That input isn't always available. How an engine finds out a token account's mint or owner is up to the engine: a wallet that can read chain state just reads it, while one that can't (typically a signing device) relies on a trusted source to provide it. That source might not exist or might be unreachable. In that case the predicate has nothing to evaluate, and the engine hasn't decided anything.
Every predicate MUST report unresolved when an input it needed wasn't available, including an input it reads indirectly through another port.
mintPredicateisSignerisAnotherSignercreatedInTransactionaccountUsedElsewhereA port therefore has three outcomes:
The outcomes combine as a three-valued AND. A single false predicate decides the port no matter what else couldn't be read, so
false AND unresolvedis inactive, whiletrue AND unresolvedis unresolved.A port's amount can end up in the same three states, for the same reason. An
argumentAmountNodereads a path in the instruction data, and that path might return nothing: the argument can be inside anoptionthe transaction left unset, or inside an enum variant that wasn't selected. The engine then has no figure for a movement it otherwise has every reason to believe happens, so the port is unresolved, whatever its predicates said.Inactive and unresolved ports are both excluded, since in both cases there is no amount or token to show. The difference is in what the rest of the pipeline is allowed to conclude from the empty slot. An instruction with an unresolved port is pinned:
hideConditionsNode.Doing any of these would claim something the engine couldn't verify.
Exclusion does not renumber
The merge uses port positions as the descriptor's own pairing, in two places:
A.outputs[k]facesB.inputs[k]across a junction, and inside the consumed item,C.junction[k]relaysC.farside[k].Excluding a port must not renumber the ports around it. If an engine indexed only the remaining ports, a port removed at one position and another removed elsewhere could shift the two directions by different amounts, and the legs ending up face to face would be legs the descriptor never paired. The consumed symmetry invariant doesn't catch this, because it only counts the legs on each side, without checking which leg faces which.
This holds no matter why the port was excluded (inactive or unresolved predicate, an amount whose path resolved to nothing, an unset optional account slot, etc.).
accountResetNode
Declares that an instruction creates or resets an account, which gives it a known balance. The engine uses these declarations for two things:
resetValueis set and noresetScopeis declared, to resolvebalanceAmountNodeon input ports of subsequent instructions referencing this account.These two uses are separate. A reset with a
resetScopeonly serves the first one: it MUST NOT go into the known-balance map, so nobalanceAmountNodeever resolves against it. See Scoped resets.All the safety rules are in the descriptor. The engine itself has no built-in knowledge of specific instructions.
Balance domains
Every balance claim applies to one domain, the triple
(account, valueKind, mint). A reset declares its domain withvalueKindand, forsplToken, with thetokennode that identifies the mint.Both structures the engine maintains MUST be keyed by that triple, never by the account address alone:
balanceAmountNode, andThis gives four rules:
balanceAmountNodeon a port only resolves against a known balance in the port's own domain, where the port'smintis the one itstokennode resolved to.valueKind, ansplTokenreset without atokennode, or a token reference that no association or attestation resolved) establishes nothing and covers nothing. The same goes for an unscoped claim whose figure can't be resolved, that is a declaredresetValuewhose argument path returns nothing because the argument is inside an unsetoptionor an enum variant that wasn't selected.The domains really are independent. A token account with no tokens left still holds lamports, and an address can hold lamports before it even becomes a token account. So a zero
splTokenreset says nothing about whatSPL:SyncNativewould wrap, and a lamport figure fromSystem:CreateAccountisn't a token amount forSPL:CloseAccountto drain.The native domain of a token account
An initialized token account always holds its rent-exempt reserve, and a wrapped-SOL account also holds the lamports backing the tokens it already reports. A
nativewhole-balance leg can't use either of these. What such a leg moves is the account's unsynced wrappable excess:SPL:SyncNativesetsamount = lamports − rent_exempt_reserve, so for a wrapped-SOL account the excess is exactly the amount a sync would newly wrap.So a
nativereset on a token account MUST setrequireNativePreBalanceZero, and the trusted source MUST attest that excess asnativePreBalancein the token-account state. The reset only holds if that figure is zero. This is a different test fromrequirePreBalanceZeroand can't replace it: an address pre-funded with SOL has a zero token balance but a non-zero excess, which is exactly the case this check is meant to catch.This is why an ordinary wrap still collapses but a pre-funded one doesn't.
{ "version": 2, "inputs": [], "outputs": [], "accountResets": [ { "kind": "accountResetNode", "account": "tokenAccount", "valueKind": "splToken", "token": { "kind": "accountMintTokenNode" } }, { "kind": "accountResetNode", "account": "ata", "valueKind": "splToken", "token": { "kind": "accountMintTokenNode", "fallbackAccount": "mint" }, "requirePreBalanceZero": true }, { "kind": "accountResetNode", "account": "ata", "valueKind": "native", "requireNativePreBalanceZero": true }, { "kind": "accountResetNode", "account": "ata", "valueKind": "splToken", "token": { "kind": "accountMintTokenNode" }, "resetValue": { "kind": "argumentAmountNode", "argument": "ataBalance" } } ] }kind"accountResetNode"accountvalueKind"native"or"splToken": the domain this reset applies to. A reset with any other value, or none, establishes nothing and covers nothingtokensplTokentoken. MUST be absent fornative, since its mint is always wrapped SOLrequirePreBalanceZerofalsesplTokenonly. Iftrue, the account is only safe when the attestedpreBalanceis"0"or absent (for idempotent creates)requireNativePreBalanceZerofalsenativeonly, and REQUIRED for anativereset on a token account. The account is only safe when the attestednativePreBalance(its unsynced wrappable excess) is0resetValue0. Ignored whenresetScopeis setresetScopeAn account can have one reset per domain.
There are two kinds of reset:
requirePreBalanceZero: false, the default). Either the instruction fails at runtime if the account already exists (non-idempotent variants likeSystem:CreateAccount), or it explicitly resets the effective balance (as Jupiter'ssetTokenLedgerdoes). The account is always added to the safe set.requirePreBalanceZero: true). The instruction can silently succeed when the account already exists with a non-zero balance (idempotent variants likeAToken:CreateIdempotent). The account is only added to the safe set if thepreBalancereturned by RPC is0or absent. The RPC call must go through a trusted source known to the wallet.A known balance set by
resetValueis invalidated by any later instruction that lists the account as writable in its raw account list, whether or not it declares a value-flow port on it. Read-only references never invalidate it, since reading can't change a balance. Such a write invalidates all domains of the account, not just the one the instruction seems to touch (see rule 4 of Balance domains).Inside a single instruction, the reset is applied after the instruction's own writes and ports. So an instruction that both writes to an account and resets it leaves the balance known (
System:CreateAccountWithSeedwrites the account it creates). This ordering is all there is to the exemption, and it matches the one in the depositor check: the declaring instruction's write is the reset that sets the figure.The same ordering decides when a safe-set entry applies. The reset describes the state after its declaring instruction, so it only bounds a balance read by a later instruction. The Symbolic Junction Guard applies this when it uses the set.
A scoped reset doesn't establish any known balance, and it also invalidates any known balance already recorded for the account, in all domains. A reset whose domain doesn't resolve, or that is missing its
requirePreBalanceZero/requireNativePreBalanceZeroconfirmation, invalidates in the same way: the instruction still ran and still wrote to the account.When
resetValueis set, the on-chain program is responsible for checking that the account holds the declared balance. If that check fails, the transaction MUST revert.Scoped resets
Some program-level resets only establish a known balance for a specific group of consumer instructions in the same program, not for the actual on-chain balance. The typical example is Jupiter's
setTokenLedger. It doesn't zero the token account: it records the current balance in a Jupiter-owned ledger PDA. Only Jupiter's*WithTokenLedgerentry points subtract that snapshot to compute the effective delta. Every other program still sees the full account balance.So a scoped reset MUST NOT establish a known balance. It only adds a safe-account entry:
balanceAmountNodeon any input port stays symbolic across it, including on an input port of an instruction the scope allows.resetScopelimits the safe-set entry with a predicate that is evaluated against each instruction relying on the reset (each item holding a symbolic leg on the reset account during a Rule 2 merge). This isn't necessarily the consumed item. When neither side of the junction names an amount, Rule 2 by default consumes the upstream item, and the survivor is the one still moving a whole balance after the collapse. If the predicate only applied to the consumed side, a snapshot restricted to one program could vouch for another program moving the whole balance of the same account.{ "kind": "accountResetNode", "account": "tokenAccount", "resetScope": { "kind": "programInstructionScope", "programId": "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4", "instructions": [ "routeWithTokenLedger", "sharedAccountsRouteWithTokenLedger", "sharedAccountsExactOutRouteWithTokenLedger", "exactOutRouteWithTokenLedger" ] } }A
programInstructionScopematches a candidate instructionixwhen:ix.programId == scope.programId, andscope.instructionsis omitted (any instruction of that program matches), orix.instructionName ∈ scope.instructions.ixcovers every item holding a symbolic leg on the reset account, and the Symbolic Junction Guard requires all of them to match. An entry that matches no leg owner isn't used by anyone, and it doesn't exempt its declaring instruction from the fully-accounted depositor check either.mintAssociationNode
Ephemeral token accounts, created and destroyed within the same transaction, don't appear in RPC
token_balances. The mint address is, however, in the account list of the instruction that creates them, and this node declares the mapping.{ "kind": "mintAssociationNode", "account": "tokenAccount", "mint": "mint" }kind"mintAssociationNode"accountmintOnce the declaring instruction is annotated, the engine adds
{address_of(account): {mint: address_of(mint)}}to the mint map, so that later instructions can resolve the ephemeral ATA. Earlier instructions don't see it (see Association order and conflicts).Example:
System:CreateAccountfollowed byToken:InitializeAccount. The system program creates a raw account,InitializeAccountbinds it to a mint, and themintAssociationNodemakes that binding visible to later instructions.{ "kind": "instructionNode", "name": "initializeAccount", "accounts": [ {"kind": "instructionAccountNode", "name": "account", ...}, {"kind": "instructionAccountNode", "name": "mint", ...}, {"kind": "instructionAccountNode", "name": "owner", ...}, {"kind": "instructionAccountNode", "name": "rent", ...} ], "plugins": [ { "kind": "pluginNode", "name": "srfc41.valueFlow", "payload": { "version": 2, "inputs": [], "outputs": [], "mintAssociation": { "kind": "mintAssociationNode", "account": "account", "mint": "mint" } } } ] }The same applies to
InitializeAccount3, for both SPL Token and Token-2022.ownerAssociationNode
A token account can be bound to an owner within the same transaction, either through
InitializeAccount{,2,3}or through the ATA program.ownerAssociationNodedeclares that binding so the engine can work it out during annotation. It has the same structure asmintAssociationNode(sameaccountfield, same place in the payload), except that the second field isownerinstead ofmint, andownercan take one of two shapes.The first shape,
accountRefNode, resolves to the pubkey of a named instruction account. It is meant forAToken:CreateIdempotentand similar instructions where the owner is passed as an account:{ "kind": "ownerAssociationNode", "account": "ata", "owner": { "kind": "accountRefNode", "name": "owner" } }The second shape,
argumentRefNode, resolves through the decoded arguments, using the same dotted paths asargumentAmountNode. OnlypublicKeyTypeNodeleaves give a usable address. It is meant for instructions likeToken:InitializeAccount2, where the owner is passed as an instruction argument:{ "kind": "ownerAssociationNode", "account": "account", "owner": { "kind": "argumentRefNode", "path": "owner" } }Association order and conflicts
A
mintAssociationNodeorownerAssociationNodedescribes something the Solana runtime enforces starting from the declaring instruction. Before that instruction, the account holds whatever was on chain, which can be a different mint and a different owner (for example a token account that was closed and re-initialized at the same address). So the engine only applies each association to the instructions after the declaring one.Every lookup of an account's mint or owner, whether for a port's token, a reset's domain, an
isSigner/isAnotherSignertarget or an ownership label, is done on behalf of one instruction. It sees the attested state plus the associations declared by earlier instructions. After a merge, a lookup for a surviving item is done on behalf of the survivor's own instruction. If nothing covers the account at that point, it is unresolved: the display is less precise, but it never shows the wrong token or owner.The engine MUST refuse to clear-sign the transaction when:
isSignerconstraint). For the owner, the comparison is made against the attested owner itself, whether or not the binding meets the canonical-ATA requirement.hideConditionsNode
Declares transaction-level conditions for hiding an instruction after the merge.
An item pinned by an unresolved predicate is never hidden, whatever the rules say.
Single rule set (AND semantics):
{ "kind": "hideConditionsNode", "rules": [ {"target": {"kind": "accountRefNode", "name": "account"}, "condition": "createdInTransaction"}, {"target": {"kind": "accountRefNode", "name": "destination"}, "condition": "isSigner"} ] }Multiple rule sets (OR of ANDs):
{ "kind": "hideConditionsNode", "ruleSets": [ [ {"target": {"kind": "accountRefNode", "name": "account"}, "condition": "createdInTransaction"}, {"target": {"kind": "accountRefNode", "name": "destination"}, "condition": "isSigner"} ], [ {"target": {"kind": "argumentRefNode", "path": "owner"}, "condition": "isSigner"} ] ] }The instruction is hidden when any rule set passes (OR between sets). Inside a rule set, all conditions must hold (AND).
rulesis shorthand for aruleSetswith a single element.kind"hideConditionsNode"rulesruleSets* Exactly one of
rulesorruleSetsmust be present.Each rule:
targetconditionThe
targetfield uses the same shapes asownerAssociationNode.owner:{"kind": "accountRefNode", "name": "<instruction account name>"}.{"kind": "argumentRefNode", "path": "<dotted path>"}. OnlypublicKeyTypeNodeleaves produce usable addresses.If a
targetcan't be resolved (missing argument, leaf that isn't a pubkey, unknown account name), the rule evaluates tofalse.Condition vocabulary
createdInTransaction(account, 0, null)of an instruction earlier in the transactionisSigneraccountUsedElsewhereaccountEffectsDisplayedElsewhereisAnotherSignerThe scopes aren't interchangeable, and the two structural predicates look in different directions.
createdInTransactiononly looks backwards, per rule 1 of Port activation.accountUsedElsewherelooks at every other instruction in both directions, because it only claims that the address is referenced somewhere in the transaction, and a later reference proves that just as well as an earlier one.accountUsedElsewhereis a structural predicate. It proves that the account address appears outside the current instruction, including in raw account lists. It doesn't prove that the other instruction displays what is lost by hiding the current one. Since it is structural, it reads declarations and not activation results. That's why it can look in both directions without breaking rule 2 of Port activation: its answer can't change once another port'sactiveWhenis settled.accountEffectsDisplayedElsewhereis the stronger predicate for hiding lifecycle instructions, and it can only be used inhideConditionsNode. An account effect is any transaction-level fact about the target account that the clear-sign pipeline gets from the instruction being hidden and then relies on for display, merge or hide safety. The generic effect set includes:balance, the token and value kind, andaccountResetNodesemantics.mintAssociationNodeandownerAssociationNode.A survivor's leg covers a hidden leg only if it is on the same account, its amount is concrete and equal, its
valueKindis compatible, the two legs have agreeing token identity, and the two legs form a hand-off, defined as follows:(account, 0, null)creation marker, moves nothing, so its direction doesn't matter. Any survivor leg on the account that meets the other conditions covers it, in either direction and in either order.A leg that moves value can only be covered by a later instruction.
Hiding settles to a fixed point
accountEffectsDisplayedElsewhererelies on another instruction showing the effect. But that instruction might itself be hidden by its own rules, in which case the effect isn't shown anywhere.So the Hide stage makes two passes over the surviving instructions, once per transaction. Nothing is re-evaluated on the fly while instructions are being hidden:
Why backward, and why one pass is enough. A hide can only be broken by something later in the transaction. When pass 1 evaluated an instruction, everything before it was already settled, and pass 2 only un-hides, so an earlier witness that was visible at that point stays visible. Any wrong assumption made by pass 1 is therefore about later instructions, and going from back to front settles every possible witness before the hides that depend on it. When pass 2 re-checks instruction i, everything after i is final and everything before it can only become visible, so a hide that passes its re-check still holds against the final hidden set.
Two more rules complete this:
A conforming implementation MUST be:
Schema examples
Example 1:
transferCheckedA Token-2022
transferChecked, with Codama's own display metadata plus the value-flow plugin. This is the smallest useful value flow: one input port, one output port, and no resets, associations or hide conditions.The display part below comes from upstream, copied as is from
registry/spl/spl_token_2022.jsoninstead of being written for this document. This is on purpose: an example written in the spec author's own style is exactly where subtle differences from the real vocabulary go unnoticed.{ "kind": "instructionNode", "name": "transferChecked", "optionalAccountStrategy": "programId", "display": { "kind": "instructionDisplayNode", "intent": "Transfer tokens", "interpolatedIntent": "Transfer ${data.amount} ${accounts.mint} from ${accounts.source} to ${accounts.destination}" }, "provides": [ { "kind": "providedNode", "name": "decimals", "node": {"kind": "argumentValueNode", "name": "decimals"} } ], "plugins": [ { "kind": "pluginNode", "name": "srfc41.valueFlow", "payload": { "version": 2, "inputs": [ { "kind": "valueFlowPortNode", "valueKind": "splToken", "account": "source", "amount": {"kind": "argumentAmountNode", "argument": "amount"}, "token": {"kind": "accountMintTokenNode", "fallbackAccount": "mint"} } ], "outputs": [ { "kind": "valueFlowPortNode", "valueKind": "splToken", "account": "destination", "amount": {"kind": "argumentAmountNode", "argument": "amount"}, "token": {"kind": "accountMintTokenNode", "fallbackAccount": "mint"} } ] } } ], "accounts": [ { "kind": "instructionAccountNode", "name": "source", "isWritable": true, "isSigner": false, "isOptional": false, "display": {"kind": "instructionAccountDisplayNode", "label": "From"} }, { "kind": "instructionAccountNode", "name": "mint", "isWritable": false, "isSigner": false, "isOptional": false }, { "kind": "instructionAccountNode", "name": "destination", "isWritable": true, "isSigner": false, "isOptional": false, "display": {"kind": "instructionAccountDisplayNode", "label": "To"} }, { "kind": "instructionAccountNode", "name": "authority", "isWritable": false, "isSigner": "either", "isOptional": false, "defaultValue": {"kind": "identityValueNode"} } ], "arguments": [ { "kind": "instructionArgumentNode", "name": "discriminator", "defaultValueStrategy": "omitted", "type": {"kind": "numberTypeNode", "format": "u8", "endian": "le"}, "defaultValue": {"kind": "numberValueNode", "number": 12}, "display": {"kind": "structFieldDisplayNode", "skip": "always"} }, { "kind": "instructionArgumentNode", "name": "amount", "docs": ["The amount of tokens to transfer."], "type": { "kind": "numberTypeNode", "format": "u64", "endian": "le", "display": { "kind": "amountNumberDisplayNode", "decimals": {"kind": "injectedValueNode", "key": "decimals"} } } }, { "kind": "instructionArgumentNode", "name": "decimals", "type": {"kind": "numberTypeNode", "format": "u8", "endian": "le"}, "display": {"kind": "structFieldDisplayNode", "skip": "whenInjected"} } ], "discriminators": [ {"kind": "fieldDiscriminatorNode", "name": "discriminator", "offset": 0} ] }The value-flow layer describes the instruction as taking value from
sourceand putting it intodestination. The amount is decoded from theamountargument, and the token is resolved from each account's mint, withmintas the fallback (remember thatfallbackAccountnames the mint, while a port's ownaccountis a token account whose.mintis read). The engine uses this to chaintransferCheckedwith neighboring instructions through shared accounts.Example 2:
createIdempotentAn Associated Token Account creation. It doesn't move any user value, and it shows why a payload with empty port lists is still useful: everything that matters here is in the resets, the associations and the hide rules.
{ "kind": "instructionNode", "name": "createIdempotent", "optionalAccountStrategy": "programId", "display": { "kind": "instructionDisplayNode", "intent": "Create Token Account" }, "plugins": [ { "kind": "pluginNode", "name": "srfc41.valueFlow", "payload": { "version": 2, "inputs": [], "outputs": [ { "kind": "valueFlowPortNode", "valueKind": "splToken", "account": "ata", "amount": {"kind": "literalAmountNode", "value": 0}, "token": {"kind": "nullTokenNode"} } ], "accountResets": [ { "kind": "accountResetNode", "account": "ata", "valueKind": "splToken", "token": {"kind": "accountMintTokenNode", "fallbackAccount": "mint"}, "requirePreBalanceZero": true } ], "mintAssociation": { "kind": "mintAssociationNode", "account": "ata", "mint": "mint" }, "ownerAssociation": { "kind": "ownerAssociationNode", "account": "ata", "owner": {"kind": "accountRefNode", "name": "owner"} }, "hideConditions": { "kind": "hideConditionsNode", "rules": [ {"target": {"kind": "accountRefNode", "name": "ata"}, "condition": "accountUsedElsewhere"}, {"target": {"kind": "accountRefNode", "name": "owner"}, "condition": "isSigner"} ] } } } ], "accounts": [ { "kind": "instructionAccountNode", "name": "payer", "isWritable": true, "isSigner": true, "isOptional": false, "display": {"kind": "instructionAccountDisplayNode", "skip": "always"} }, { "kind": "instructionAccountNode", "name": "ata", "isWritable": true, "isSigner": false, "isOptional": false, "display": {"kind": "instructionAccountDisplayNode", "label": "Token Account"} }, { "kind": "instructionAccountNode", "name": "owner", "isWritable": false, "isSigner": false, "isOptional": false, "display": {"kind": "instructionAccountDisplayNode", "label": "Owner"} }, { "kind": "instructionAccountNode", "name": "mint", "isWritable": false, "isSigner": false, "isOptional": false, "display": {"kind": "instructionAccountDisplayNode", "label": "Token Mint"} }, { "kind": "instructionAccountNode", "name": "systemProgram", "isWritable": false, "isSigner": false, "isOptional": false, "display": {"kind": "instructionAccountDisplayNode", "skip": "always"} }, { "kind": "instructionAccountNode", "name": "tokenProgram", "isWritable": false, "isSigner": false, "isOptional": false, "display": {"kind": "instructionAccountDisplayNode", "skip": "always"} } ], "arguments": [ { "kind": "instructionArgumentNode", "name": "discriminator", "defaultValueStrategy": "omitted", "type": {"kind": "numberTypeNode", "format": "u8", "endian": "le"}, "defaultValue": {"kind": "numberValueNode", "number": 1}, "display": {"kind": "structFieldDisplayNode", "skip": "always"} } ], "discriminators": [ {"kind": "fieldDiscriminatorNode", "name": "discriminator", "offset": 0} ] }Value-flow layer:
atausesliteralAmountNode(0)andnullTokenNode. It shows a creation marker without adding value to the chain. An emptyinputslist together with a zero-amount, null-token output is what tells a creation apart from an instruction that produces value.accountResetswithrequirePreBalanceZero: trueexpresses the idempotent behavior. The ATA is only added to the safe-account set if its on-chain pre-balance is zero or absent. This allows later symbolic-junction merges, for exampleSyncNativefollowed by a swap readingbalanceon the same ATA, as required by the Symbolic Junction Guard.mintAssociationis added to the mint map once the create is annotated, so later instructions can resolveata's mint without an RPCtoken_balancesentry.ownerAssociationdeclares thatatais owned byowner. The runtime enforces this (the ATA address isPDA(owner, mint, tokenProgram)), so the engine can evaluateisSigner(ata)without on-chain state.hideConditionshides the create after the merge only if the ATA is referenced elsewhere in the transaction and the owner is the device signer. Together, these prevent the ATA-create attack, where a malicious creator opens an ATA for someone else.The
"Token Account","Owner"and"Token Mint"labels are not in the plugin. They are regular Codama display metadata, in the instruction's own nodes. The plugin only carries what Codama can't model. If a curator moves a label into the payload because it is easier to edit there, no Codama consumer will ever read it.Security Considerations
Advanced-user display
Merge and hide only change what is displayed. They are not consensus rules, and the transaction signed on-chain is always the full instruction list. A wallet implementing this extension MUST offer an opt-in advanced (or expert) view that turns off both merge and hide and shows every instruction separately, using the sRFC 39 base display, or the raw instruction when there is no display.
Whether this view is on by default or behind a "show details" control is a wallet UX decision and out of scope here. The only requirement is that it exists and can be reached.
Amount Guard
Rule 1 requires equal numbers, which prevents false merges between unrelated operations that happen to share an account. The engine must never show the user spending less, or receiving more, than they really do.
Port amount renderability
The Amount Guard decides which collapses happen. This section is about whether what a collapse moves is actually shown.
Take a chain where the first item takes 2000 from the user and passes 1000 on, leaving the rest in an account that no port declares:
The junction legs agree, so Rule 1 fires and instruction 1 is consumed. This isn't a false merge. What keeps the collapse honest is amount propagation, which rewrites the survivor's input port to
(A, 2000). The merged item shows what really leaves the user's own account. The leftover amount isn't hidden: only the internal account it ended up in is.But the engine can't put that 2000 on screen by itself. It fills runtime values into the survivor's display fields, matching a port with an argument through the path they both read, and renders it with the
amountNumberDisplayNodeon that argument's type. If the survivor's junction port reads a path that none of the survivor's amount fields displays, nothing matches, the survivor keeps showing its own1000, and the review shows the user paying less than they do. Both figures are instruction data, so the host can choose how much goes unshown, within what the program accepts.The rule itself isn't the problem. Requiring the consumed item's two legs to balance would refuse this collapse, but it would also refuse every honest relay that takes a fee, and it isn't what protects the user anyway, since propagation already does. What's missing is a guarantee that the propagated figure has a field to land in. That is a property of the descriptor, decided before any transaction exists. This is the reason for the renderability requirement on
valueFlowPortNode, checked when descriptors are curated.Junction Token Guard
Both rules require agreeing token identity on every junction port pair. Without this check, the engine could combine A's numeric amount with B's token identity and show something like "Transfer 2,000,000,000 USDC" when the real intent was a 2 SOL transfer.
The guard is checked as part of the account match, before the rule is classified, so it applies to Rule 1 as well as Rule 2. If it only applied to Rule 2, Rule 1 would rely only on numeric equality to decide that two legs are the same, and equal numbers say nothing about what is being moved.
A missing mint is an unknown, not an agreement. This is all the guard says, and reading it the other way would make it useless for native SOL. For example:
The two instructions meet on
attacker_account. Instruction 1's outgoing port isnativeand names no mint, and instruction 2's incoming port names its mint. If the missing mint counted as compatible, the token check could never fail. The kind check acceptsnativeagainstsplTokenon purpose (see below). And amounts are compared as raw integers, where 1 SOL is 1,000,000,000 lamports and 1000 units of a six-decimal token is also 1,000,000,000. So the pair would be classified as a numeric chain, instruction 1 would be consumed, and the review would show a single token transfer from the user's own wallet. The SOL going to an account the attacker controls would not be shown at all.The attacker doesn't need to wait for a lucky coincidence. Both figures are raw integers chosen by the host, so the attacker just looks at the token amount the user is already sending and picks the lamport amount that equals it. Every SPL transfer has a matching SOL amount, and both instructions succeed on chain, since any account can receive lamports. The intermediate account is controlled and signed for by the attacker: it receives the SOL from the folded instruction and is also the source shown on the remaining screen.
Mixing kinds must only be allowed for wrapping. Letting
nativematchsplTokenis correct in itself: when SOL is wrapped, the account looks like one kind on one side and the other kind on the other side, and the device should be able to collapse that. But what restricts this to wrapping is the token check, which verifies that the SPL side holds wrapped SOL. If the token check can't fail, the kind check gives no extra protection, and only the amount comparison is left. That's why Token identity has a Native state: a native port states the wrapped-SOL mint, so a wrap still collapses and anything else still fails on a mint mismatch.A moved amount keeps its units. A related problem has the same cause but needs its own defense, because it can happen even when the identities agree. When the surviving port carries a whole balance instead of a stated amount, the fold takes the consumed port's account and amount. If it didn't also take the
valueKindthe amount was measured in, and only took the token when the consumed side has one, a native consumed port (which has no token) would leave the survivor with an amount of lamports under an unrelated token's identity and decimals. Whether this shows up on screen depends on how the renderer resolves the amount for such a port, but nothing in the merge would detect or fix it, and the fold would always produce it. ThevalueKindpropagation rule is what keeps an amount and its units on the same port.Recipient propagation safety
Rule 2 always takes the concrete far-side account from the consumed item. If a
CloseAccountsends funds away from the signer, that destination appears in the final output and is never silently replaced or hidden. Two defenses ensure this together, and the creation-marker survivor guard makes sure a transaction can't slip through the gap between them.Take a swap that outputs WSOL, followed by a malicious
CloseAccountthat sends the unwrapped SOL to an attacker:CloseAccountmerges with Rule 2, because both junction amounts are symbolic, and its destination is copied into the surviving output:output: 0.5 WSOL to [attacker_address].CloseAccount's destination, so the attacker's address appears in the merged intent.CloseAccount'shideConditionsNoderequiresisSigneron the destination. The attacker isn't the device signer, soCloseAccountstays visible as a separate item.When the close targets a balance that already existed, defense 2 is the only one that applies. Defense 1 never kicks in: the instruction before the close isn't symbolic, so no merge happens and there is no surviving output for the destination to be copied into. So the attacker won't name their own address as the destination, since defense 2 catches that. Instead, they'll look for a destination that passes
isSignerbut is still under their control. A token account owned by the victim but whose close authority is the attacker is exactly that, which is why an attested binding is only accepted for a canonical ATA of the attested owner.Symbolic balance merge safety
Any merge that puts a symbolic amount (
balanceAmountNode) on S can hide a difference in value when the account it reads already had a balance: if C has the symbolic amount, the display shows S's numeric amount while C's drain actually takes the full balance. That symbolic leg can be at the junction or on the far side copied by the collapse, and the far-side case can happen under either rule.The symbolic junction guard prevents this with three checks:
accountResetNodedeclarations, otherwise the merge is blocked. AresetScopeon the entry is evaluated against every item holding a symbolic leg on the account, S included, and all of them must match. A reset scoped to one program means nothing to other programs, which still see the full account balance, even when one of them is the survivor. The entry must also be in effect when the leg is read: it covers nothing if it was declared after the earlier of S and C, and a far-side input drained by C needs a reset declared strictly before C.C = A, each one must pass checks 1 and 2 for its own account. WhenC = B, the junction leg feeding it must pass them, which happens automatically for a symbolic junction leg but not for a numeric one.Why the first two checks are not enough on their own
Checks 1 and 2 establish one fact: the junction holds exactly what this merge chain put into it. That bounds a symbolic drain of the junction, and nothing else. It doesn't bound a symbolic fill, because a zero reset only constrains the account's starting balance, not how much is deposited into it.
Both directions can reach Rule 2, but only one of them is safe:
In the second case, Rule 2 by default consumes A, since A names fewer amounts at the junction. Amount propagation then keeps S's
100because C's far side is symbolic, while account propagation takessource. The result says that 100 leftsource, when in factsourcewas emptied and the rest is stuck in the junction account. Check 3 refuses this collapse, and A stays on screen with its drain still shown as symbolic.The account at risk here is the far-side one, which the first two checks never look at. A guard that only checked the ports facing the junction would let this transaction through.
An exact relay bounds the junction and nothing else
The same blind spot on the far side also affects Rule 1, where the junction gives the guard nothing to check at all:
Both figures at the junction are instruction data chosen by the host, so this needs no reset, no attested account state and no hide rule. The second descriptor only has to declare a stated amount coming in and a whole balance going out.
The danger comes from what the collapse does with that far leg. Rule 1 copies C's far leg onto S as is, symbolic amount included, and
balanceAmountNodeis exempt from the renderability requirement, so no field of S has to be able to render it. At best the movement shows up in the review without an amount. A renderer that only fills in numeric port amounts will instead keep S's own argument on screen, showing a fixed figure for an unbounded movement. Check 3 refuses the collapse unless the junction passes checks 1 and 2, and that is also what still allows the honest version of this chain to collapse.Unrecognized instructions
An instruction is unrecognized when it has no recognized IDL
instructionNode(unknown program, unknown discriminator, or a descriptor with no display overlay). Unrecognized instructions are a security risk, because they might modify accounts whose balance, owner, mint, reset state or display/hide predicate the merge engine relies on.Wallet vendors MAY turn off intent-less removal, merge and hide for the whole transaction as soon as any instruction is unrecognized. In that mode, each instruction is shown with the sRFC 39 base per-instruction display, or as a raw instruction when there is no display. How the wallet reacts in its UX (blind sign, list as is, warn) is out of scope for this specification.
Wallet vendors MAY run the merge engine around unrecognized instructions only if they can verify that those instructions don't write to any account the merge engine uses. Partial merging is unsafe if an unrecognized instruction can modify an account that matters for the merge.
Common side instructions, like memo, compute budget, priority fee or tip patterns, and other standard ecosystem programs, should still have curated IDLs, so devices can tell harmless instructions apart from unknown value movements.
isSignerconstraintisSignerMUST match the device user's signing key, not the fee payer or any other signer of the transaction. It also matches ATAs owned by the device signer, so that lifecycle instructions likeToken:CloseAccount, which reference a signer-owned ATA instead of the signer's pubkey itself, can be hidden.Two sources of
ata_ownersare accepted:ownerAssociationNodedeclarations. These cover accounts the transaction creates or initializes, and they can be trusted because the Solana runtime enforces them from the declaring instruction onwards. Either (a) the ATA isPDA([owner, tokenProgram, mint], AssociatedTokenAccountProgram)and a wrongownerargument makes the instruction fail, or (b)InitializeAccount{,2,3}writesownerinto the token account header when it runs. A transaction-derived binding only applies to the instructions after the one declaring it.If the two disagree, the engine refuses to clear-sign the transaction. The runtime only enforces a transaction-derived binding from its own instruction onwards, so it says nothing about the account before that point, and an honest transaction never re-initializes an account with a different owner. See Association order and conflicts.
Canonical-ATA requirement for attested bindings
An attested
ownersays who owns a token account, but not who can close it, and these can be different. SPL Token'sSetAuthority(CloseAccount)sets a close authority separate from the account owner, andSetAuthority(AccountOwner)can then give ownership to someone else while the close authority stays the same. (This works on a non-native account. Changing the owner of a native account does clear the close authority, so an attacker creates the account on an ordinary mint and only ever sends lamports to it.) So an account can be truthfully attested as owned by the device signer while someone else still has the right to close it and take its lamports.That alone is enough to defeat
isSigner. The engine decides the destination is the user's own account,Token:CloseAccountis hidden, and the wrapped SOL moved by the close disappears from the review. Nothing in the transaction, the descriptor or the attestation is malformed: the descriptors are the normal ones, and the attested owner really is the device signer.So when an engine evaluates
isSignerorisAnotherSigneragainst an attested binding, it MUST also require the account to be the canonical ATA of the attested owner:mintMUST come from the same attested source asowner. A binding with an unknown mint MUST be rejected, because the address can't be checked without it.tokenProgramMAY be either the SPL Token or the Token-2022 program id when the attested source doesn't say which one holds the account. Matching either one is enough, since matching the derivation under the wrong program would be a PDA collision.owner,tokenProgramandmint. It needs no secret and no attested input other than the mint, so a signing device can do it locally.This brings back the property
isSigneris relied on for. No matter who creates a canonical ATA, the Associated Token Account program initializes it with the derivation'sowneras account owner and no close authority, andSetAuthority(CloseAccount)on it needs that owner's signature. So a canonical ATA of the device signer is an account that only the device signer can close, which is exactly what recipient propagation safety assumes.A signer-owned token account that is not a canonical ATA (for example an
InitializeAccount{,2,3}keypair account) just stays visible. No value flow is lost, it only adds one review screen.Transaction-derived bindings don't have this requirement. The runtime enforces them within the transaction being signed, from the declaring instruction onwards, and any authority change would have to be an instruction in that same transaction. Wallet vendors SHOULD NOT curate a descriptor that lets an authority-changing instruction (
SetAuthorityor equivalent) be hidden, since a transaction could then change the close authority of an account it also binds without the change ever being shown.IDL authenticity (sRFC 39 alignment)
This extension reuses the IDL authenticity model of sRFC 39 and adds no trust assumptions of its own. A malicious
srfc41.valueFlowpayload could hide legitimate instructions or merge unrelated operations, but a maliciousintentstring has the same risk in the base display, and both are mitigated by curation and authenticity checks.It does add one new integrity concern, which is about maintenance rather than trust: the payload is opaque to Codama, so the identifier references inside it aren't updated by tree transformations or validated by anything upstream. An implementation MUST re-validate every reference against the base IDL whenever the base changes. See Payload references are not maintained by Codama.
Worked Examples
Example 1: Jupiter swap with WSOL wrap and close
Transaction:
[ComputeBudget:SetLimit, ComputeBudget:SetPrice, AToken:CreateIdempotent(wsol_ata), System:Transfer(0.5 SOL → wsol_ata), Token:SyncNative(wsol_ata), Jupiter:Route(0.5 WSOL → 100 USDC), Token:CloseAccount(wsol_ata)]This is the standard swap pattern from the pipeline walkthrough, followed step by step. The user pays 0.5 SOL and expects at least 100 USDC. Jupiter trades SPL tokens, so the wallet adapter wraps SOL into WSOL with
CreateIdempotent → Transfer → SyncNativebefore the swap, and unwraps it withCloseAccountafterwards. The ComputeBudget instructions affect fees but have no value flow.Step 0: Annotate.
CreateIdempotent'smintAssociationNoderecordswsol_ata = WSOL, so the ephemeral ATA can be resolved.accountResetNodewithrequirePreBalanceZero=trueaddswsol_atato the safe set when the balance before the transaction is zero, which lets later merges pass the safe-account check of the symbolic-junction guard.CloseAccount'sactiveWhenonly activates its ports for WSOL. For any other mint, the ports are excluded.Step 1: Merge.
Step 2: Hide.
The wallet displays a single intent:
"Swap 0.5 SOL for at least 100 USDC".The merge collapses
Transfer → SyncNative → Routeinto Route'sSwapintent. Transfer's SOL input from the signer is propagated by Rule 1, and SyncNative's far-side WSOL token identity is propagated by Rule 2. Both lifecycle instructions (CreateIdempotentandCloseAccount) are hidden, becausewsol_atais used elsewhere in the transaction and the signer-owned binding is verified throughmintAssociationNodeandownerAssociationNode. The ComputeBudget instructions are used to compute fees.The
amountNumberDisplayNodeon each argument's type scales the raw amounts (500_000_000 lamports → 0.5 SOL,100_000_000 USDC atoms → 100 USDC), and the survivor's template"Swap ${data.inAmount} for at least ${data.quotedOutAmount}"builds the final string.Example 2: Native staking via CreateAccountWithSeed
Transaction:
[System:CreateAccountWithSeed(amount=49.6 SOL), Stake:Initialize, Stake:DelegateStake]Step 0: Annotate.
CreateAccountWithSeed's port amounts and itsaccountResetNode.resetValueall resolve to the sameamountargument, so the reset declares a known native balance of 49.6 SOL onstake_acct.DelegateStakeonly has an input (one input, no outputs), which makes it a value transformer because its ports are asymmetric.Initializethen listsstake_acctas writable in its raw account list (the runtime modifies the stake-account header), which invalidates the known balance beforeDelegateStakeis annotated. SoDelegateStake'sbalanceAmountNodestays symbolic. Nothing in the transaction tells a header write apart from a credit.Step 1: Merge.
No merge happens here. The writable-overlap guard is positional, and
Initializelegitimately writes the stake-account header to record the staker and withdrawer authorities. Refusing to merge is safer than guessing which writes are harmless.Step 2: Hide.
Two screens remain:
CreateAccountWithSeed, showing 49.6 SOL going from the signer tostake_acct, andDelegateStake, showingstake_acctwith no amount. The amount is shown and attributed to the right account, but the two can't be merged into a single intent becauseInitializehas an undeclared write onstake_acct.Example 3: Jupiter two-hop swap and tip transfer
Transaction:
[Jupiter:setTokenLedger, Jupiter:sharedAccountsRoute, Jupiter:sharedAccountsRouteWithTokenLedger, System:Transfer]A real Jupiter v6 route splits one user swap across two pools:
quotedOutAmountin the intermediate token.WithTokenLedgervariant that reads the intermediate ATA's balance withbalanceAmountNode, using whatever hop 1 produced.setTokenLedgerruns first and records the balance before the hops in a program-owned ledger PDA, so that hop 2 can compute the difference.System:Transferat the end pays a tip to a different recipient.Step 0: Annotate.
usdc_ataandeth_ataare the signer's USDC and ETH ATAs (the route ends up back in the same USDC ATA). Both swaps are symmetric value transformers. Hop 2's input is abalanceAmountNode, a symbolic drain ofeth_ata.setTokenLedger's reset is scoped: it only allows a symbolic read ofeth_atawhen the consumer is one of Jupiter's*WithTokenLedgervariants. Since it is scoped, it doesn't set a known balance, so hop 2's input stays symbolic and the merge is decided by the guard and not by a resolved figure.Step 1: Merge.
Step 2: Hide.
The wallet renders the route and the tip as separate items:
The two-hop route collapses into a single
Swapintent.setTokenLedgerdisappears because both swaps referenceeth_ata, soaccountUsedElsewhereholds. The tip stays visible: its only port is on an unrelated account (tipper) and has a differentvalueKind(nativeinstead ofsplToken), so it can't match the merged swap.The scoped reset is what makes this collapse safe.
setTokenLedgerdoesn't zeroeth_ataon chain, it only records its balance in Jupiter's ledger PDA. Any instruction outside[sharedAccountsRouteWithTokenLedger, routeWithTokenLedger]holding a symbolic leg oneth_atawould fail theresetScopepredicate in the symbolic-junction guard and block the merge, whether it is the consumed side or the survivor. Here the only symbolic leg oneth_atais the swap's input. TheTransferthat fills it names a number, so it isn't tested against the scope.Example 4: Jupiter flash-fill order (no protocol-internal ports)
Transaction:
[AToken:Create, LimitOrder:PreFlashFillOrder, AToken:Create(wSOL), System:Transfer, Token:SyncNative, AToken:Create(JUP), AToken:Create(USDC), Jupiter:Route, Token:CloseAccount, LimitOrder:FlashFillOrder]Here a taker fills a limit order using Jupiter's flash-fill mechanism. On chain, the value goes through:
The reserve and maker accounts are protocol-internal and MUST NOT appear as ports.
Correct value flow (no protocol-internal ports):
Both instructions have asymmetric ports (one port each), so the merge can't consume them (the consumed symmetry invariant requires
len(inputs) == len(outputs)). They stay as separate visible items.Why not declare both sides? If
PreFlashFillOrderdeclaredreserveas an input andFlashFillOrderdeclaredmakerOutputAccountas an output, the merge would chainreserve → taker → wSOL → swap → JUP → maker. The final display would show the order's reserve as "Your Account" and the maker's account as "Destination", and neither of them belongs to the signer.Merge (middle chain only):
Hide: the creates of signer-owned ATAs are hidden (
accountUsedElsewhereandisSigner), andCloseAccountis hidden (isSigneron the destination).The taker sees:
The display follows the pre-fill, swap and settle steps in the order they actually run.
Appendix A: Test vectors
How to read the expected pipeline:
#2,#3, ...) refer to the parsed instructions of the transaction.Mergeentries give the merge rule, the consumed instruction, and the surviving instruction that renders the merged item.Hideentries list the predicates that caused an instruction to be hidden.Side effectsentries describe the side effects declared by the descriptor, such as account resets, known balances, mint associations and owner associations.Compute-budget instructions are left out, because fees are parsed separately and the merge engine doesn't handle them.
Minimum ReceivedforquotedOutAmount. That value is the router's quote, and the program doesn't enforce it as a minimum (withslippageBps = 10000there is no minimum at all), so the registry now labels itQuoted Outputand shows the slippage parameter next to it. The vectors were updated to match.Systemscreens and oneStakescreen showed an intent that Ledger used to override. These programs now publish their own display metadata and the registry uses it, soTransferbecomesTransfer SOLandStakebecomesDelegate stake.Otherwise, the vectors keep the naming of the device build they were written from. For example,
kamino_yvaultslabelsMaximum Token Awhere vector 7 saysMax Token A. Several vectors also annotate value-flow ports on instructions for which the registry declares none, which is a legitimate authoring choice and doesn't indicate missing coverage. These differences come from the vectors themselves. Whether to update them is a question of sRFC 41's coverage and is separate from the display vocabulary.Vector 1: Native staking
Transaction signature:
Instruction annotations:
Expected pipeline:
Expected normalized display:
Vector 2: Jupiter v6 WSOL to Pepe swap
Transaction signature:
Instruction annotations:
Expected pipeline:
Expected normalized display:
Vector 3: Jupiter v6 USDC to SOL swap
Transaction signature:
Instruction annotations:
Expected pipeline:
Expected normalized display:
Vector 4: Jupiter v6 USDC arbitrage route with token ledger and tip
Transaction signature:
Instruction annotations:
Expected pipeline:
Expected normalized display:
Vector 5: Jupiter perps increase position
Transaction signature:
Instruction annotations:
Expected pipeline:
Expected normalized display:
Vector 6: Kamino unstake token pair
Transaction signature:
Instruction annotations:
Expected pipeline:
Expected normalized display:
Vector 7: Kamino wrap SOL and stake token pair
Transaction signature:
Instruction annotations:
Expected pipeline:
Expected normalized display:
Vector 8: Kamino swap and stake token pair
Transaction signature:
Instruction annotations:
Expected pipeline:
Expected normalized display:
All reactions