THORChain Protocol Upgrade v3.21

Monero takes center stage in THORChain v3.21. One of the network's most anticipated integrations is now a step closer to activation, with this latest wave of merge requests addressing critical aspects of signing, recovery, and operational readiness.

Beyond Monero, v3.21 brings several other improvements:

• A one-time state migration corrects historical bond and pool accounting and restores the ETH.THOR pool.
• Solana gains support for the new transaction format that halted trading, clearing the way for it to resume.
• Zcash trading can resume after fixes to how ZEC outbounds are matched.
• Memoless Swaps get new spam protection ahead of their return.
• Limit Swaps can be turned back on, with fixes for the bugs that bloated THORChain's state.
• The App Layer gets the fixes it needs to restart after the Rujira FIN exploit.
• A redesigned affiliate rewards system keeps each integration's earnings and payouts separate, letting SwapKit switch THORChain back on for its partners.
• Bond providers get Streaming Yield, a new way to take part of their rewards as income without waiting for their node to churn out.

The release also includes a broad range of stability, security, and reliability improvements across chains, assets, node operations, and outbound execution.

Monero Gets Ready for Activation

Monero is getting closer to launch, but integrating a privacy-focused chain brings challenges that go well beyond simply signing transactions.

Building on v3.20, this release strengthens nearly every part of the XMR integration, from FROST key generation and reorg recovery to scanner reliability, spent-output tracking, and signing readiness. The objective is to ensure the network can recover safely when things don't go as planned.

XMR activation remains gated and requires a follow-up v3.21.1 release. Once accomplished, the integration will follow the usual soft-launch approach, with rounds of testing and shallow liquidity during the initial weeks.

MR !5026 - FROST Keygen & Rollout Hardening
Improves FROST keygen coordination, prevents messages from being lost when nodes progress through rounds at different speeds, and introduces explicit controls for enabling XMR keygen.

MR !5045 - Least Authority Follow Up: Harden FROST Stream Lifecycle and DKG Delivery
Adds retry handling for FROST keygen messages and strengthens stream cleanup and signer handling, following recommendations from the Least Authority XMR audit.

MR !5068 - XMR Reorg & Errata Recovery
Makes XMR reorg outcomes durable so recovery can continue across validator churns and restarts without repeating slashing or accounting effects.

MR !5109 - Preserve XMR Reorg History
Keeps the reorg history needed for recovery while a vault catches up, preventing important transaction history from disappearing too early.

MR !5112 - Scanner Recovery After Churn
Allows the XMR scanner to safely rewind and resume after a node becomes active, including when the recovery process is interrupted by a restart.

MR !5111 - Safer XMR Quote Destinations
Prevents quotes from accepting XMR destination types that the signer can't support and stops invalid unsigned outbounds from repeatedly blocking valid transactions.

MR !5037 - Safer XMR Refund Addresses
Requires an explicit refund address for XMR swap and limit-order quotes, ensuring funds can be returned safely if a transaction fails.

MR !5120 - XMR Catch-Up Finalization
Allows spent-output information recovered directly from THORChain consensus to be finalized during catch-up.

MR !5121 - Recover XMR Outbounds From Consensus
Rebuilds missing outbound and spent-reference information from THORChain's persisted consensus state after churns, restarts, or historical recovery.

MR !5124 - XMR Startup & Signing Readiness
Prevents XMR recovery problems from blocking Bifrost startup for every other chain and only allows XMR signing once the required recovery state is ready.

MR !5052 - XMR Network Verification
Makes Bifrost verify that the Monero signer and daemon are connected to the correct network before allowing the XMR client to start.

MR !5153 - XMR Consolidation Mimirs Become Operational
Makes XMR consolidation controls operational Mimirs, allowing node operators to quickly tune or disable consolidation while the integration is still new.

Mainnet State Migration & Recovery

v3.21 introduces a significant state migration to correct historical accounting issues and restore liquidity across several areas of the protocol.

The migration includes reversing a historical bond slash that affected 218 bond providers, reconciling Secured-Ops liquidity donations, restoring the ETH.THOR pool, and retiring the synthetic assets of seven low-utilization pools.

MR !5175 - Mainnet State Migration
Introduces the migration needed to correct historical bond and pool balances, restore ETH.THOR liquidity, and retire the synthetic assets of selected pools, with safeguards against inconsistent accounting.

Solana Outbounds Get More Resilient

SOL trading was halted after Solana activated a new transaction format in mid-September that Bifrost couldn't read, breaking Solana fee sampling on every node. v3.21 ships the fixes needed to resume trading.

Solana's short-lived blockhashes create a second challenge for THORChain: when signing takes too long, transactions can expire before they are broadcast, particularly during vault migrations.

v3.21 introduces an optional durable nonce mechanism to give Solana outbounds a longer signing window. Combined with improved recovery for expired and stuck transactions, this makes outbound execution more resilient when signing doesn't go according to plan.

MR !5091 - Solana Versioned Transaction Support
Lets Bifrost read Solana's new versioned transactions, restoring fee sampling and making sure vault deposits sent in these formats are observed. This fix first reached Bifrost in the v3.20.3 patch.

MR !5128 - Solana Durable Nonces
Allows each SOL vault to use a durable nonce so outbounds no longer depend entirely on short-lived recent blockhashes. The feature is Mimir-gated and disabled by default.

MR !5154 - Durable Nonce Queue Recovery
Fixes an edge case where multiple exhausted SOL outbounds from the same vault could end up waiting on each other indefinitely.

MR !5096 - Solana Blockhash Expiry Recovery
Improves how Bifrost detects expired or unavailable Solana signing blockhashes, preventing migrations from retrying an impossible signing attempt for the entire signing window.

Affiliate Accounting Gets Reworked

Previously, if one owner controlled multiple THORNames, those THORNames could share the same Affiliate Collector. That meant fees earned by different integrations could be pooled together, making it harder to track who earned what and which payout settings should apply.

v3.21 changes this by giving each THORName its own Affiliate Collector. Affiliate fees, REVSHARE, and preferred payout settings are now tracked separately for each integration.

The change opens the door to cleaner multi-partner affiliate programs. Wallets, aggregators, and other integrators can operate multiple THORNames under one owner without mixing revenues, recipients, or payout assets. The fix also allows SwapKit to turn THORChain back on for several of its integrators.

MR !5086 - Separate Affiliate Collectors
Gives every THORName its own Affiliate Collector, separating affiliate fees, REVSHARE, and preferred-asset payouts between integrations.

Streaming Yield for Bond Providers

Bond providers usually have to wait for their node to churn out before they can withdraw their rewards. Streaming Yield, called Bond Yield in the protocol, lets them have a share of their future rewards paid out at every churn instead, while the rest is automatically rebonded.

Payouts are sent in RUNE to the provider's own address, another THORChain address, or a THORName the provider owns, which can convert them into its preferred asset through its Affiliate Collector. The node operator fee is taken first, and existing bond and rewards already earned still follow the usual unbond rules. The feature ships disabled and goes live once enabled through Mimir.

MR !4814 (commit 12cee82a) - Bond Yield Payouts
Adds the BONDYIELD memo that lets each bond provider set the share of future rewards paid out automatically and where it goes. If a payout can't be completed, that share is rebonded instead.

Memoless Swaps Prepare to Resume

Following the expansion of Memoless Swaps to ERC-20s in v3.20, the feature was paused after attempts to spam the system by registering large numbers of memo references.

v3.21 introduces dynamic registration costs to address this issue. Instead of charging a fixed amount, registration becomes increasingly expensive as available reference slots fill up, making large-scale spam attacks more costly.

MR !5022 - Dynamic Memoless Registration Costs
Introduces a configurable pricing mechanism that increases memo registration costs as available reference slots become occupied, helping protect Memoless Swaps against spam. Governance must enable it through Mimir; until then, registration keeps its current flat cost.

Chain & Asset Updates

Several smaller changes improve individual chain integrations and expand THORChain's Ethereum token support.

Zcash

An outbound matching issue led to a ZEC vault slash. No user funds were lost, but ZEC trading has been halted until these fixes go live.

MR !5213 - Zcash v6 Transaction Support
Updates THORChain's Zcash signer to support v6 transactions following the NU6.3 network upgrade, while preserving compatibility with existing v5 transaction checkpoints.

MR !5193 - Better TEX Address Support
Converts Zcash TEX destinations into the equivalent transparent address used by the Zcash daemon for outbound scheduling, observation, and accounting.

MR !5010 - Consistent Outbound Destination Matching
Makes all outbound matching use the same destination comparison rules, including equivalent Zcash address formats, so valid payments are correctly recognized.

MR !5099 - More Consistent ZEC Input Selection
Makes validators choose a more deterministic set of confirmed ZEC inputs, reducing the chance of TSS signing parties splitting because nodes constructed different transactions.

TRON

MR !5114 - Preserve TRON Observations During RPC Failures
Stops Bifrost from advancing past a TRON block when a required receipt lookup fails, ensuring vault deposits and outbounds aren't silently skipped.

New Ethereum Tokens

MR !5080 - cirBTC Whitelisted
Adds Circle Wrapped Bitcoin, cirBTC, to THORChain's Ethereum mainnet token whitelist.

MR !5071 - YUM Whitelisted
Adds YUM to THORChain's Ethereum mainnet token list.

App Layer & Scheduling

The App Layer has been halted since the exploit of Rujira's FIN contract. v3.21 ships the fixes needed before node operators can restart it.

v3.21 brings two changes to how the App Layer handles contract execution and scheduling. The upgrade removes an unnecessary execution delay and retires the direct Layer 1 contract invocation path.

MR !5144 - Same-Block Scheduling
Removes an extra one-block delay from the scheduler, allowing scheduled contract actions to execute at the intended block and supporting same-block scheduling when the delay is zero.

MR !5132 - Remove the X Memo
Removes the X / EXEC memo path that allowed a Layer 1 transaction to directly execute a THORChain Wasm contract.

Better Swaps, Limit Orders & Queries

Limit Swaps were paused after a bug bloated THORChain’s state. Orders that had run out of funds were never closed. Instead, the network retried them every block and stored each failed attempt’s error message, until about 670 open orders were carrying roughly 57 MB of error data.

v3.21 fixes the cause and limits the damage if something similar happens again. Underfunded orders are now settled instead of retried, the error history stored for each swap is capped, and the Advanced Swap Queue is indexed so it does less work each block as activity grows. Together, these changes allow Limit Swaps to be turned back on.

The release also makes quote and query endpoints deterministic, so every validator returns the same result for the same request.

MR !4807 - Trade/Secured Swap & Limit Order Fixes
Tracks the amount actually consumed during Trade and Secured Asset swaps and correctly settles limit orders that become underfunded or can no longer execute because of rounding.

MR !5027 - Deterministic API Queries
Removes nondeterministic behavior from quote and query endpoints, including random placeholder addresses and unstable sorting that could produce different results across validators.

MR !5012 - Advanced Swap Queue Optimization
Optimizes how swaps are indexed, matched, and processed, significantly reducing computational overhead and improving performance as trading activity increases.

MR !5125 - Advanced Swap Queue & Accounting Fixes
Limits the accumulation of failed-swap error data and fixes a validator-state caching issue that could cause inconsistencies in bond accounting.

Safer Churns & Vault Migrations

Several v3.21 changes come directly from real churn and migration failures observed on the network. The goal is to prevent one misconfigured node, one stuck chain, or one failed keygen from unnecessarily blocking the broader vault rotation process.

MR !5083 - Repair Vault Chain Sets From Late Keygen Reports
Allows late validator reports to add missing chains to a new vault and retries rotation once the vaults agree, fixing a real churn failure where SOL was missing from some newly generated vaults.

MR !5106 - Hold Misconfigured Nodes Out of Ready
Prevents a node that recently reported an incomplete chain configuration from immediately participating in another keygen and repeatedly stalling churn.

MR !5123 - Per-Chain Migration Progress
Stops a stuck migration on one chain from blocking every other chain in the same retiring vault, allowing healthy chains to keep draining.

MR !5118 - Preserve Keygen Retries
Prevents temporary API or Mimir lookup failures from permanently discarding a scheduled keygen retry.

MR !5177 - Faster Failed Keygen Retry
Fixes a timing edge case that caused failed keygens to wait two retry intervals instead of retrying on the first configured retry tick.

MR !5090 - AllowNoVault Becomes Operational
Makes the AllowNoVault-<CHAIN> emergency control an operational Mimir so nodes can open or close short insolvency-correction windows more quickly.

Outbound, TSS & Signing Reliability

v3.21 also contains a broad set of fixes designed to prevent stuck outbounds, duplicate payments, TSS retry problems, and signing races.

MR !5117 - Bond Reward Accounting Fix
Caps rounded node rewards by the actual funded bond-reward balance, preventing the network from allocating more rewards than are available.

MR !5011 - Safer Vault Reassignment
Checks every observation linked to an outbound before moving it to another vault, reducing the risk of an already-paid outbound being sent a second time.

MR !5094 - Outbound Reassignment Overflow Protection
Prevents malicious or extreme transaction observations from overflowing the amount check used during vault reassignment.

MR !5136 - UTXO Keysign Recovery
Lets BTC and other UTXO chains rebuild an unsigned transaction when a TSS signing party never forms, instead of repeatedly retrying a transaction that validators disagree on.

MR !5029 - Replay-Safe TSS Failures
Ensures a completed TSS keysign-failure vote can't be replayed to repeatedly trigger slashing, jail time, vault freezing, or accounting changes.

MR !5113 - Signer Lock Race Fix
Fixes a concurrency issue that could crash Bifrost when signing workers finished while new vault and chain signing locks were being created.

MR !5093 - Signer Constants Cache Fix
Synchronizes access to shared signer configuration values, removing a race between concurrent signing processes.

MR !5081 - TSS Signer Filtering Override Becomes Operational
Makes the emergency DisableTSSSignerFiltering control an operational Mimir so it can be changed quickly when required.

MR !5131 - Better UTXO Diagnostics
Improves error reporting so operators can tell whether a vault's UTXOs are genuinely missing from the node or were simply excluded by transaction-selection rules.

Development, Security, Testing and Documentation

The remainder of the release focuses on dependency security, monitoring, testing, simulation, and development infrastructure.

MR !5178 - Go Security Update
Updates the Go toolchain to 1.26.9 to incorporate standard-library security fixes.

MR !5140 - CosmWasm Dependency Update
Updates wasmvm and wasmd to newer maintenance releases, together with the required dependency updates.

MR !5043 - Expanded Network Monitoring
Adds 175 monitoring metrics across THORChain, giving node operators better visibility into vaults, solvency, swaps, and network health. It also addresses a potential consensus issue in telemetry.

MR !5049 - New Debugging Logs Endpoint
Introduces an optional API endpoint allowing node operators to retrieve protocol logs for specific block ranges, making network issues easier to investigate.

MR !5182 - eBifrost Data Integrity
Protects cached quorum and event data against unintended modifications, improving reliability during transaction observation and consensus processing.

MR !5104 - Shared Signer & Simulation Readiness
Strengthens the test and simulation environment used to validate XMR signing, churns, scanner recovery, and cross-chain readiness before activation.

MR !5101 - Ethereum Test Race Fix
Fixes a race in Ethereum test configuration and properly cleans up mock servers between tests. This is test-only.

MR !5095 - More Reliable Mocknet Startup
Retries temporary EVM readiness failures and prevents partially initialized genesis state from being treated as a valid mocknet deployment.

MR !5087 - Stronger CI Safety Checks
Makes several previously ineffective CI checks actually fail when problems are found, adds Bifrost race testing, and catches additional signer concurrency issues.

MR !5074 - Regression Test Reliability
Prevents the regression runner from crashing when an HTTP request fails before returning a response.

MR !5089 - Release Documentation Fix
Corrects the documented path for THORChain's changelog generation script.

MR !5061 - Incentive Pendulum Documentation Fix
Corrects the documented behavior of PendulumUseVaultAssets so it matches the actual protocol logic.