Merlin swap
Merlin swap record and balance reconciliation
Merlin swap reconciliation succeeds when the confirmed execution record and the output-token balance describe the same state change. Record the opening balance and quote conditions before signing, then reconcile the confirmed transfer with the resulting balance change after accounting for other movements in the same asset. Trace any difference before considering another exchange.
Updated:
Before another submission is considered, a confirmed output transfer should reconcile with the credited balance change after accounting for other movements in the same asset.
Capture the exchange state before commitment
Before the wallet displays a signature request, write down the receiving account, network, input amount, output token identity and opening output balance. A balance figure without its account and token contract is ambiguous. The same symbol can appear on more than one token contract, while a smart-account wallet may hold assets at an address different from the signer.
Keep the quote alongside those values. Its estimated output, minimum received amount and visible fees describe the condition that you were willing to accept. If any field changes while you are still reviewing, reject the request or refresh the quote. Nothing needs to be reconciled until a swap transaction is actually submitted.
This snapshot fixes the comparison point. Later figures must use the same account, network and token identity or the arithmetic will describe a different ledger entry.
Quote terms that define the expected outcome
The exchange details panel shows the liquidity-provider fee, price impact, average price and minimum received amount before signing. These fields answer different questions. The estimate describes the calculated output for the displayed state, while the minimum received amount sets the lower boundary that the submitted exchange may accept.
Price impact reflects how the requested exchange interacts with available liquidity. It is not a second charge deducted after execution. The liquidity-provider fee belongs to the exchange calculation, whereas the network fee pays for processing the transaction. Record both, but do not subtract the network fee from an ERC-20 output balance unless that fee was actually charged in the same asset and account being compared.
A quote is therefore an acceptance condition rather than a reserved balance. If the refreshed quote changes before commitment, the newer signed terms replace the older figures in the reconciliation record.
The commitment point and the separate approval
The input and acceptance terms can change until the swap transaction is signed. You can still withhold a signed transaction before submission, but changing its contents requires a new signature.
A token approval may appear first when the exchange contract lacks sufficient allowance. That approval changes how much of the input token the contract may spend. It does not prove that the exchange executed, and its transaction hash must not be mistaken for the swap hash.
The wallet preview is the final place to compare the requested action with the saved quote.
Once the swap is broadcast, assume that it may execute. Closing the wallet or refreshing the interface does not cancel an included transaction. A second submission can create another exchange rather than repair the first one, so establish the original hash and status before taking further action.
Read the execution record as state evidence
The relevant execution record establishes whether the requested swap succeeded or failed. For a direct EVM transaction, record the receipt's hash, network, sender, destination, block and status. If a smart-account wallet submits an operation, identify that operation within its enclosing transaction instead of treating the outer sender and receipt status as proof of the swap's result. A successful direct receipt or smart-account operation result confirms that the relevant call did not revert, but the transferred output still has to be identified among the transaction events and related balance changes.
An ERC-20 token movement is recorded through a Transfer event emitted in the transaction logs. For reconciliation, match the output token contract and credited recipient rather than selecting the largest or last event. A routed exchange may emit intermediate transfers that do not represent what reached the receiving account. Convert a raw token value with that token's declared decimals before comparing it with the wallet display.
A native-asset movement does not use an ERC-20 Transfer event. Its balance comparison must account for network gas and any other native-asset movements made by the same account during the measured interval.
Which balance should change after execution?
The balance that should change belongs to the address credited with the final output transfer. This may be the visible wallet address, a smart-account address or another recipient encoded in the transaction. The connected signer alone does not settle that question.
For an ERC-20 output, read the recipient from the relevant output event, then compare that address before and after the confirmed block. For a native output, identify the credited address from the execution trace or balance changes before making the same comparison. Where a wallet uses account abstraction, the signer may authorize an action while a smart account holds the resulting token. Checking the signer's separate balance would create an apparent shortfall even though the credited account received the output.
Keep input and output ledgers separate. The input balance falls according to the amount spent, while the output balance rises according to the amount delivered. Fees and unrelated transfers belong in their own entries.
Separate the wallet display from the chain state
A wallet screen is a rendered view of ledger data, and that view can lag or omit a token. The underlying balance may already be correct.
Network identity comes first. Merlin Mainnet uses chain ID 4200, so a balance displayed under another network does not describe the same state. Next, match the account and token contract. A hidden token, stale cache or incorrect decimal rendering can change what the interface shows without changing the on-chain balance.
Use a balance reading tied to a confirmed block when the display remains uncertain. If the raw balance rose by the recorded transfer amount, the exchange reconciles at the ledger level and the remaining problem is presentational. If the raw balance did not rise, continue with the recipient, token identity and event path rather than treating the screen as the only evidence.
A hypothetical input change with two outcomes
All quantities in this worked example are hypothetical. The opening output balance is 41.26 units. An input of 12.6 units produces an estimated output of 8.48 units and a minimum received amount of 8.32 units. Nothing has been signed, so the input and acceptance condition remain editable.
On the normal path, the reader accepts that first quote. The confirmed record shows an output transfer of 8.39 units. With no other movement in the output token, the closing balance becomes 49.65 units. The transfer and balance increase agree.
In the edge case, the reader changes the input to 13.6 units before commitment. A refreshed quote estimates 9.12 output units with a minimum of 8.93. The reader signs only this later request. The confirmed transfer is 9.01 units, which raises the same opening balance to 50.27 units.
Comparing 9.01 with the stale 8.48 estimate creates a false mismatch. The later signed terms govern the exchange. If the correct address does not reach 50.27 units and no other output-token movement occurred, the arithmetic no longer closes and the mismatch needs further tracing.
Trace an unchanged wallet display
Consider the narrow case in which the receipt succeeded and the logs show an output transfer to the intended account, yet the wallet display appears unchanged. Compare the chain, account, token contract and decimal precision with the opening snapshot. A difference in any one of them means that the two displayed figures are not comparable.
If those identifiers match, inspect the raw balance at a block before execution and at a confirmed block after it. An increased raw balance points to a stale or incomplete wallet presentation. An unchanged raw balance means the selected event may belong to an intermediate transfer, another recipient or another token contract. Preserve the original transaction hash while resolving that distinction.
Submitting the exchange again does not correct a display problem. It introduces another transaction and another set of balance changes.
Failed, pending and confirmed records
A pending record has no settled output to reconcile. Its displayed estimate can remain visible while the request awaits inclusion, is replaced or disappears from a wallet's activity view. Check whether the original request or a replacement was included before deciding its status. For an externally owned account, compare transaction hashes that use the same nonce; a smart-account wallet may expose a separate operation identifier linked to an enclosing transaction.
A failed EVM transaction reverts the requested contract state changes while still consuming network gas. The output-token increase should therefore be zero unless another transaction moved that token during the same interval. The native balance may still be lower because the failed attempt used gas.
Once the direct receipt or smart-account operation result confirms success, move the review to token events and balances. Confirmation alone does not identify which event represents the final output, so the token contract, recipient and amount still have to agree.
How can token identity create a false mismatch?
Token identity creates a false mismatch when the opening and closing figures refer to different contracts, networks or decimal scales. A ticker is display text rather than a unique on-chain identifier. Two wallet entries can share a symbol while representing different ledger entries.
Use the output token contract from the executed route and retain its decimal value for conversion. Wrapped and native forms also belong to separate balances even when their names appear related. A native balance will not increase merely because a wrapped token reached the account, and importing a token into a wallet changes its visibility rather than its on-chain quantity.
If the transaction events identify the expected contract but the wallet lists another one, the wallet entry is the mismatch. The confirmed transfer should be compared with the contract that emitted it.
Close the comparison with durable evidence
Reconciliation is complete when the saved opening state, signed acceptance condition, confirmed transaction and closing balance describe one consistent change. Retain the transaction hash, chain ID, credited account, output token contract, raw transfer amount, decimal scale and before-and-after balances. For a smart-account request, also retain its operation identifier. These details allow the calculation to be repeated without relying on a transient wallet label.
For an isolated interval, closing balance minus opening balance should equal the received transfer. When the interval contains additional activity, closing balance minus opening balance should equal the received transfer plus other incoming movements minus other outgoing movements. Network gas belongs in a separate native-asset calculation unless the output itself is that native asset.
In the worked figure above, 50.27 - 41.26 = 9.01 output units.
Merlin swap - your questions answered
Does a replaced transaction change the hash used for reconciliation?
For an externally owned account, yes. A replacement transaction has a different hash even though it reuses the earlier request's nonce. Reconcile the transaction that was included and confirmed, not a hash left in a stale wallet notification. For a smart-account request, follow its operation identifier to the enclosing transaction and use the operation result, output events and balance changes as the final record.
Can an unrelated token transfer distort the measured balance difference?
Yes. Any incoming or outgoing movement of the same token between the opening and closing snapshots changes the arithmetic. Compare the swap's recorded transfer with all movements for that account and token during the interval. A balance increase larger or smaller than the exchange output is not automatically an execution error when another transfer occurred.
Is the wallet's rounded balance suitable for exact reconciliation?
No; a rounded wallet balance can conceal small differences, so exact reconciliation should use the token's raw before-and-after values, apply its declared decimal scale and compare the resulting change with the confirmed output transfer while accounting for any other movements of that token during the same interval.
Should the opening balance be captured before approval or immediately before the swap?
Capture the comparison balance as close as possible to the swap submission and identify the corresponding block. A token approval normally changes allowance rather than the approved token balance, although it may consume native gas. If approval or another transaction occurs between snapshots, record those effects separately so the output-token calculation still covers the intended exchange interval.