Shutting Down a Cosmos App Chain and Migrating to Solana

1. Why Solana Is a Good Fit

Prerequisite: this runbook covers the operational side of retiring an app chain and relaunching on Solana. The code-level work of rewriting CosmWasm contracts as Solana programs is covered in the CosmWasm migration guide — read that first, because the phases below assume the contract rewrite is planned or underway.

Do not start a migration because another team did. The strongest reason to choose Solana is that the network already operates at the scale most app chains are working toward:

Secure: one globally distributed validator set secures every program, so your team inherits deep shared security instead of operating its own validators.
100M+ quarterly active wallets: a live user base to acquire from instead of bootstrapping activity on an isolated chain.
$2T annual DEX volume and $10B+ DeFi TVL: real liquidity and market structure for your token to plug into on day one.
Billions of transactions per quarter at fees under $0.0025: consumer-scale activity stays affordable for users and for your own operational jobs.
Mature developer ecosystem: established program frameworks, testing resources, RPC providers, indexers, wallets, and payment rails.

Two tradeoffs still deserve honest validation before you commit: native IBC interoperability does not carry over, so plan a bridge or protocol-specific integration, and CosmWasm contracts need a real rewrite to Solana's account model rather than a port.

On Solana, a program is executable onchain code, an account is the durable state that programs read and write, and a transaction is the signed bundle of instructions that asks programs to do work. If that model fits your product and operations, the migration has a stronger foundation.

Architecture differences: Cosmos app chains vs Solana

Use this mapping when you are translating operational responsibilities and state architecture, not just contract code.

Cosmos app chain	Solana destination
Modules and/or CosmWasm contracts	Programs
Module KV stores and shared chain state	Program-owned accounts and PDAs
Governance proposal plus chain upgrade	Governance-controlled authorities and program upgrades
Validator set operated by the app chain	Shared Solana validator set; app teams operate programs and off-chain services
Cross-module or contract invocation	CPI with explicit account metas
IBC interoperability	Bridge or protocol-specific cross-chain integration
Bech32-encoded account addresses, typically backed by secp256k1 account keys	Base58-encoded Ed25519 wallet addresses
Genesis export and state snapshot	Merkle roots, claim programs, and replayable migration jobs

2. Phase 0: Planning & Announcement

Internal alignment

Do this before any public message goes out.

Agree on a target halt window internally. Ninety days from public announcement is a sensible minimum.
Inventory every user-held asset: liquid balances, staked balances, unbondings, LP positions, NFTs, vesting, escrow, and contract balances.
Map every contract and module to one of three outcomes: migrate, replace, or deprecate.
Audit every active IBC channel and identify external relayer operators and counterparty teams.
Contact major validator operators privately before the public announcement.
Give listed exchanges meaningful notice before the public migration window begins.
Prepare a coordinated user communications plan: synchronized announcements across your channels plus persistent banner notifications on your site, apps, and block explorers, each linking to a canonical migration info page. The channel-by-channel communication plan in Phase 6 is the template to start filling in now.
Draft the governance proposal and the technical shutdown runbook in parallel.
Decide what the migration portal will need to do for identity linking and claims.

Community governance

Even if the team can coordinate a validator halt without formal governance, skipping governance usually destroys trust. The operationally clean approach is to publish a temperature-check discussion first and a binding governance action later.

The proposal should explain the new Solana asset clearly. Most migrated fungible tokens become SPL tokens: tokens managed by Solana token programs rather than by your retired Cosmos chain.

Text

Title: [Deprecation Proposal] Shut Down CHAIN_NAME and Migrate to Solana

Summary:
The team proposes to sunset CHAIN_NAME on DATE, migrate TOKEN to Solana as an SPL token,
and redirect development resources to the Solana ecosystem.

Rationale:
- Security, liquidity, ecosystem, or product fit reasons
- Data supporting the decision

Migration plan:
- Token migration architecture
- Smart contract migration path
- Timeline and exchange coordination
- Unclaimed token policy

Recommended timeline

Text

Day 0:   Public announcement and forum proposal
Day 14:  On-chain governance vote opens
Day 21:  Governance vote closes
Day 28:  Migration portal opens and exchange work begins
Day 90:  Chain halts at the pre-announced block height
Day 180: Optional migration-claim deadline

Large communities should bias toward longer windows, not shorter ones.

3. Phase 1: Cosmos Chain Shutdown (Technical)

Set the halt block height

Choose a height far enough in the future that validators, exchanges, relayers, and users can act. Every validator should configure the same halt height.

TOML

# ~/.chain/config/app.toml
halt-height = 12345678

Bash

chaind start --halt-height=12345678

The halt block is committed. Nodes stop before processing the next block. If the chain is on an older Cosmos SDK version, insist on exact binary consistency across validators before the halt.

Export final state

Bash

chaind export --height=12345678 --for-zero-height > final_state.json

Use the resulting state as the canonical record for balance extraction and later audit work.

Bash

cat final_state.json | jq '.app_state.bank.balances' > final_balances.json
cat final_state.json | jq '.app_state.staking.delegations' > final_delegations.json
cat final_state.json | jq '.app_state.staking.unbonding_delegations' > final_unbonding.json

Compute the canonical snapshot

For a 1:1 token migration, merge bank balances, delegations, unbondings, module balances you intend to honor, and any contract-side token balances you promise to preserve.

Python

# snapshot_merge.py - pseudocode
snapshot = {}

for entry in balances:
    addr = entry["address"]
    amount = sum(c["amount"] for c in entry["coins"] if c["denom"] == "utoken")
    snapshot[addr] = snapshot.get(addr, 0) + int(amount)

for delegation in delegations:
    addr = delegation["delegator_address"]
    tokens = shares_to_tokens(delegation["shares"], delegation["validator_address"])
    snapshot[addr] = snapshot.get(addr, 0) + int(tokens)

for entry in unbonding:
    addr = entry["delegator_address"]
    for ubd in entry["entries"]:
        snapshot[addr] = snapshot.get(addr, 0) + int(ubd["balance"])

Do not trust the pipeline until totals reconcile to the supply you intend to preserve.

Handle IBC channels

Pause relayers before the halt so no new packets enter the queue.
Drain or timeout in-flight packets intentionally.
Notify counterparty chains and relayer operators with real dates, not vague warnings.

Transfer (ICS-20) channels cannot be force-closed with close-init — the transfer module rejects user-initiated closes. Wind them down by pausing relayers and letting in-flight packets time out, then coordinate counterparties on the halt date.

Validator offboarding

Ask validators to archive their final node state and signing-state files.
Pay or reconcile any final commission or support obligations before they disappear.
Publish a formal validator offboarding memo with the halt height, export steps, and archive expectations.

Text

Subject: Validator Offboarding - Action Required

The chain will halt at block HEIGHT on DATE.
1. Configure halt-height=HEIGHT
2. Export final state after halt
3. Archive your node data to cold storage
4. Confirm your final commission destination

4. Phase 2: Token Migration Architecture

For most chain shutdowns, the cleanest design is a snapshot-driven Merkle tree claimer on Solana. Instead of keeping a bridge alive after the Cosmos chain halts, you finalize balances off-chain, commit one Merkle root on Solana, fund a claim vault, and let each user prove their entitlement once.

A Merkle root is a compact cryptographic commitment to the full claims file. A claim vault is a token account funded with the migration supply. The claim program verifies each proof, releases the right SPL token amount, and records that the claim is complete. A working reference is available in the example Merkle token claimer.

Recommended architecture: Merkle tree claimer

Take a final Cosmos snapshot and normalize the balance dataset you intend to honor.
Convert each claim into a deterministic leaf such as {index, cosmos_address, solana_address, amount} or {index, recipient, amount}.
Build the Merkle tree off-chain and publish the root plus the full snapshot artifact for community review.
Deploy a Solana claim program that stores the Merkle root, vault authority, token mint or token-vault accounts, and claim window.
Require each claimant to submit their amount, leaf index, and Merkle proof, then mark that leaf as claimed in onchain state.

Text

Cosmos final snapshot
  -> normalized claims file
  -> Merkle tree build
  -> published root + claim JSON
  -> Solana claimer program initialized with root
  -> token vault funded
  -> users submit proof and receive SPL tokens

What the Solana claimer should own

In the Rust-style structs below, Address is the current Solana SDK type for an address: the base58-encoded public key of an account, program, mint, vault, or wallet. Anchor programs still name the same 32-byte type Pubkey, which is why the Anchor snippets in this guide use that name.

Rust

pub struct Distributor {
    pub merkle_root: [u8; 32],
    pub mint: Address,
    pub vault: Address,
    pub vault_authority_bump: u8,
    pub claim_window_end_ts: i64,
}

pub struct ClaimStatus {
    pub index: u64,
    pub claimed: bool,
}

A simple implementation uses one Program Derived Address (PDA) or bitmap entry per leaf index to prevent double claims. A PDA is a deterministic address controlled by a program instead of a user's private key. The claim instruction recomputes the leaf hash, verifies the Merkle proof against the stored root, transfers or mints the exact SPL amount, and then records the claim status before returning.

Rust

pub fn claim(
    ctx: Context<Claim>,
    index: u64,
    amount: u64,
    proof: Vec<[u8; 32]>,
) -> Result<()> {
    require!(!ctx.accounts.claim_status.claimed, ClaimError::AlreadyClaimed);
    require!(
        verify_proof(
            ctx.accounts.distributor.merkle_root,
            hash_leaf(index, ctx.accounts.recipient.key(), amount),
            &proof,
        ),
        ClaimError::InvalidProof
    );

    transfer_from_vault(&ctx, amount)?;
    ctx.accounts.claim_status.claimed = true;
    Ok(())
}

transfer_from_vault is where a Cross Program Invocation (CPI) happens: the claim program calls the SPL Token program to move tokens from the vault into the claimant's token account. Because the vault authority is a PDA, the program signs that CPI with the authority's seeds instead of a private key. In Anchor the transfer looks like this:

Rust

token::transfer(
    CpiContext::new_with_signer(
        ctx.accounts.token_program.to_account_info(),
        token::Transfer {
            from: ctx.accounts.vault.to_account_info(),
            to: ctx.accounts.recipient_token_account.to_account_info(),
            authority: ctx.accounts.vault_authority.to_account_info(),
        },
        &[&[b"vault_authority", &[ctx.bumps.vault_authority]]],
    ),
    amount,
)?;

If per-claim rent matters at your scale, a rent-free variant tracks spent claims in Merkle state instead of in receipt accounts. Each claim submits an exclusion proof that its leaf is not yet in a stored spent-claims root plus the updated root that includes it, the program verifies both against the same sibling path, and then swaps the root in place. The Solana Foundation's private-channel escrow program implements this pattern with a sparse Merkle tree. It is cheaper to administer and removes the rent barrier for claimants, in exchange for serializing claims on the root account and requiring your proof service to track the evolving spent set.

Why this architecture is usually better

You only need one canonical balance export, not a live cross-chain relay after shutdown.
Anyone can audit the published claims file and recompute the Merkle root before launch.
The on-chain program stays small: proof verification, token release, and replay protection.
Support operations get simpler because each failed claim is tied to a specific leaf, proof, and recipient address.

Unclaimed token policy

Policy	Description	Tradeoff
Burn	Unclaimed balances disappear after the window.	Simple but punitive.
Community treasury	Unclaimed balances move to multisig or DAO control.	Flexible but politically sensitive.
Extended claim escrow	Hold balances for a longer claim period under a governed escrow.	User-friendly but more operational work.
Permanent program escrow	Leave unclaimed balances claimable in the program escrow forever, with no deadline.	The least hostile to users, but the "real" circulating supply stays permanently uncertain.
Decaying claims	Build a decay factor into the claim program: for example, 100% of the allocation for the first year, then decreasing linearly to zero by year two.	Creates urgency without a hard cliff, but adds program logic and still needs a destination for the decayed remainder.

A long or permanent escrow-based claim window is usually the least hostile choice for real users.

5. Address Linking

Cosmos users usually hold Bech32-encoded account addresses while Solana wallets use base58-encoded Ed25519 public keys, so the migration needs a deterministic way to link a source-chain account to a destination wallet before the claims file is final.

Keep the layers separate in your design: Bech32 is an address format, Cosmos account keys are usually secp256k1 for transaction signing, and validator consensus keys are a different identity entirely. Do not assume a validator key or node operator identity should map to a user claim.

Recommended: pre-registration plus a carefully scoped fallback

Primary: before the snapshot, let users register their Solana address on Cosmos so the migration artifact already contains the intended destination.

Fallback: if your wallet and support flows can reliably access the original Cosmos account signing key, you can offer a signature-based recovery path for users who missed pre-registration. Treat this as a recovery mechanism, not the default UX, because operational support is more complex and some users will no longer have a compatible signing flow.

Example: preregistration record

JSON

{
  "cosmos_address": "osmo1...",
  "solana_address": "7Yp...base58...",
  "snapshot_height": 12345678,
  "nonce": "migration-v1"
}

6. Phase 3: Launching on Solana

Create the SPL token

An SPL token has a mint account that defines the token's decimals, supply controls, and authorities. Match the migrated token's precision deliberately, and decide whether you need the standard Token Program or Token Extensions for features such as transfer fees, metadata, or compliance controls.

Bash

solana-keygen new --outfile migration-authority.json
solana config set --keypair migration-authority.json
solana config set --url mainnet-beta

spl-token create-token --decimals 6 > token_address.txt

mainnet-beta is Solana's production cluster. Rehearse the full launch on a local validator or devnet before you run these commands for real.

Since you are deploying a claim program anyway, consider creating the mint deterministically from that program instead of from a CLI keypair: initialize the mint at a PDA with a program-controlled authority, so the mint address derives from your program and the authority handoff is explicit program logic rather than an operational step. The create-token program example shows mint creation from program code.

Add metadata

Without token metadata, wallets and aggregators will show an opaque mint address. Fix this before you send users to the new chain.

Attach it with the Metaplex Token Metadata program, which works with mints from both the Token Program and Token-2022, or use the built-in metadata extension if you created the mint with Token-2022. If you script the launch instead of using the CLI, Create a Token Mint walks through the same steps in code and links both metadata options at the end. Either path points to a JSON file you host:

JSON

{
  "name": "Your Token Name",
  "symbol": "TKN",
  "description": "Migrated from CHAIN_NAME Cosmos chain to Solana.",
  "image": "https://your-metadata-server.com/logo.png",
  "external_url": "https://yourproject.com"
}

Mint supply and lock authorities deliberately

Bash

spl-token create-account MINT_ADDRESS
spl-token mint MINT_ADDRESS 1000000000
spl-token authorize MINT_ADDRESS mint --disable
spl-token authorize MINT_ADDRESS freeze --disable

A mint authority can create more tokens, and a freeze authority can freeze token accounts. Only revoke these authorities after you verify supply, vault custody, and operational signers. Disabling them is a one-way action.

Multisig, token lists, and liquidity

Move treasury and migration vault control to a multisig such as Squads.
Bridge the treasury assets you need on day one: native USDC moves from Cosmos (Noble) to Solana through Circle's Cross-Chain Transfer Protocol, and other assets need an established bridge route you have rehearsed with a small transfer first.
Fund operational wallets with mainnet SOL for deploys, rent, and fee payers before cutover week, and review the Solana Foundation grants and funding page for ecosystem support programs.
Submit token metadata to the venues and registries your users will rely on.
Seed at least one meaningful liquidity venue before the migration rush begins.

7. Phase 4: Smart Contract / Program Migration

The contract rewrite itself is covered in the CosmWasm migration guide. Operationally, this phase is about deciding which live chain state must survive and how it will be represented as Solana accounts.

Categorize every contract and module

Text

Category A - Migrate with state
Category B - Migrate logic only
Category C - Deprecate
Category D - Replace with native Solana equivalents

For anything in Category A, design the target account layout before writing migration jobs. Solana programs are stateless executables, so durable balances, positions, schedules, and configuration must live in accounts owned by the relevant program.

Vesting migration

Financial obligations such as vesting schedules need exact treatment. Export them explicitly and initialize equivalent Solana state, not ad-hoc spreadsheets. In Anchor, a Rust framework for Solana programs, #[account] marks a struct that will be serialized into a Solana account.

Bash

cat final_state.json | jq '.app_state.wasm.contracts' |   python3 extract_vesting.py > vesting_positions.json

Rust

#[account]
pub struct VestingSchedule {
    pub recipient: Pubkey,
    pub total_amount: u64,
    pub start_timestamp: i64,
    pub end_timestamp: i64,
    pub claimed_amount: u64,
    pub bump: u8,
}

The program around that state needs two instructions: a funding instruction that locks the tokens and a claim instruction that releases only what time has unlocked.

create_new_vest: validate the schedule before writing it — amounts above zero, start_timestamp before end_timestamp, and a recipient that matches the exported Cosmos data. Initialize the schedule PDA from stable seeds such as [b"vesting", recipient], store the bump, set claimed_amount to zero, and transfer the full allocation into a vault owned by the program's PDA authority in the same transaction, so a schedule can never exist unfunded.
claim_vest: require the claimant to sign and match schedule.recipient, read the current time from the Clock sysvar, and compute the vested amount with checked math — linear interpolation between the timestamps, plus whatever cliff rules you exported. Pay out vested - claimed_amount, update claimed_amount before transferring from the vault via the PDA signer, and reject claims where nothing new has vested.

You do not have to design this from scratch. The Solana developer bootcamp's token-vesting project is a buildable Anchor program with exactly this instruction shape — create the schedule accounts, then a Clock-driven claim with cliff handling — and Bonfida's token-vesting program is a Kudelski-audited implementation deployed on mainnet. If your exported schedules are standard cliff-plus-linear shapes, also consider loading them into an existing vesting product such as Jupiter Lock or Streamflow instead of operating a custom program.

NFT migration

CW721 metadata is closer to Solana's than it looks. A CW721 token points at off-chain JSON through token_uri (or stores the same fields on-chain in its metadata extension), and those fields follow the OpenSea-style standard. Metaplex JSON shares the core fields, so name, description, image, animation_url, external_url, and attributes usually carry over unchanged — a well-formed existing token_uri can often be reused as-is.

Map the differences deliberately: Metaplex JSON also expects a category and a properties.files array with a URI and MIME type per file; royalty configuration moves out of the JSON into onchain royalty settings such as the Metaplex Core Royalties Plugin; and CW721-only fields like background_color and youtube_url have no direct equivalent. Re-host any metadata or media you do not control on durable storage before the source chain halts.

Pick the Solana NFT or digital-asset standard before writing claim logic. For large collections, Bubblegum compressed NFTs keep mass minting affordable — on the order of 5 SOL all-in for a million assets — but wallets and marketplaces read them through DAS-API indexers rather than plain account fetches, so confirm your target tooling supports them first.
Preserve provenance and identifiers intentionally where external integrations depend on them.
Distribute with the same Merkle pattern as the token claimer: snapshot CW721 ownership as {contract, token_id, owner, solana_address} leaves, publish the root, and let each owner claim a mint of the corresponding Solana asset (for compressed assets, the claim instruction mints via CPI into Bubblegum).

DeFi positions

Liquidity positions: snapshot LP balances and the asset ratios you need to honor at migration time. Decide whether users receive migrated LP positions, underlying assets, or a fresh liquidity program entry on Solana.

Lending and borrowing: snapshot collateral, liabilities, and risk state. Resolve bad debt and policy exceptions before migration so you do not import insolvency into a new environment.

Delegation and rewards: define how staking, pending unbonding, and accrued rewards map into the Solana-side product.

What usually does not migrate 1:1

Validator operations: your app no longer owns a dedicated validator set after the move.
IBC channels and client state: these need a new cross-chain integration plan rather than a literal port.
Module internals: Cosmos module parameters and store layouts rarely map cleanly into Solana account layouts.
Indexer assumptions: dashboards and support tooling usually need a new read model built around Solana accounts and logs.

Solana constraints to plan around

Programs are stateless: durable migration data must live in accounts, not inside the executable.
Account allocation has cost: account sizing, rent, and resize strategy affect both migration design and user experience.
Transaction envelopes are bounded: large claims, proof payloads, or fan-out jobs may need to be chunked across multiple instructions or batches.
Compute per transaction is finite: expensive verification or multi-program flows need budgeting and profiling before production rollout.
Operational jobs must be restartable: large migrations should assume retries, partial completion, and resumable execution.
Read models often move off-chain: dashboards, audits, and support tools usually depend on indexed account data rather than on-chain query entrypoints.

8. Phase 5: Governance Migration

Realms is the main DAO and treasury-management interface for Solana. It sits on top of SPL Governance, the Solana governance program, and gives you proposal workflows, voting configuration, DAO treasuries, and governed execution for actions such as treasury transfers and program upgrades.

If your Cosmos chain used on-chain governance for signaling, treasury control, or upgrade approval, the closest Solana-native destination is usually a Realm plus one or more governed treasuries. The migration is not one-to-one: Cosmos governance controls chain state, while Solana governance usually controls assets, program authorities, and operational workflows.

Cosmos model	Solana destination
Text proposals	Snapshot or other off-chain governance process
Parameter changes	Governed admin program or multisig-controlled program authority
Upgrade proposals	Squads or similar controlled upgrade-authority flow
Community pool	Realms or treasury multisig

Realms vs. Squads

Both get described as treasury management, which makes them easy to confuse. They solve different problems:

Realms is token-weighted governance. Voting power comes from community (or council) tokens deposited into the Realm, proposals are voted on by token holders, and passed proposals execute their instructions on-chain. It is the closest analog to the Cosmos x/gov module and community pool.
Squads is a multisig. A small, named set of member keys approves transactions against an M-of-N threshold — no token voting involved. It is the tool for operational custody: day-to-day treasury operations, program upgrade authority, and mint or freeze authorities.

Most teams end up with both: community-scale decisions and the community treasury live in a Realm, while operational authorities and working funds sit in a Squads multisig that is itself accountable to the DAO.

How to migrate governance cleanly

Create the new DAO in Realms before or alongside token launch so treasury control and program authority do not live on a temporary signer longer than necessary.
Decide whether governance power comes from the migrated community token, a council token, or a dual structure where a smaller council handles urgent operations.
Move treasury assets, mint authority, freeze authority, and upgrade authority into governed accounts intentionally instead of leaving them on deployer wallets.
Rewrite recurring Cosmos proposal types as explicit Solana actions: treasury transfers, parameter updates through admin programs, and program upgrades through governed execution.

Practical mapping

An upgrade authority is the signer allowed to replace an upgradeable Solana program's executable code. A Cosmos software-upgrade proposal usually becomes a Solana program-upgrade proposal after that authority is transferred into governance. Treasury and community-pool decisions usually become Realms treasury proposals executed by governed wallets.

The main design choice is who can propose and who can veto. Many migrations start with a council-controlled Realm for safety, then expand toward broader token voting once the token, treasury, and program authorities are settled on Solana.

9. Phase 6: User Migration & Communication

Communication plan

This is the plan you drafted during planning and announcement, now running against real dates. Day 0 is the public announcement.

Channel	Timing	Purpose
Blog post	Day 0	Full rationale, timeline, and migration mechanics
Discord, Telegram, X	Day 0	Short-form announcement and reminder cadence
Email	Day 0	Direct notice to known users and partners
Site, app, and explorer banners	Day 0 to halt	Persistent countdown and a link to the canonical migration info page
Validator and exchange outreach	Before public launch	Operational heads-up and cutover coordination

Migration portal requirements

Connect Cosmos and Solana wallets in the same flow. On the Solana side, wallet-adapter is the established React integration, and the @solana/kit react-app example shows a complete connect and sign-in flow built on the newer wallet-standard hooks.
Show eligibility and claimable amount from the canonical snapshot.
Support your chosen architecture: mapping-only, one-way bridge, or post-snapshot claim.
Provide status tracking, transaction signatures, and a user-visible audit trail.

The portal is the frontend over the claim program from Token Migration Architecture: it looks up the user's leaf in the published claims file, fetches the Merkle proof, submits the claim transaction, and surfaces the resulting signature as the audit trail.

Exchange coordination

Custodial platforms need the new mint address, conversion ratio, cutover date, test transaction, and a real technical contact. Large exchanges usually need more notice than your community does.

10. Phase 7: Decommissioning Cosmos Infrastructure

Inventory everything first

On Solana, RPC services expose account and transaction data to wallets, indexers, dashboards, and support tools. Keep enough Cosmos RPC, LCD, gRPC, and explorer infrastructure online for users to verify history while the Solana-side product becomes the source of truth.

Text

Validators:
  - primary validator
  - sentry nodes
  - seed nodes

API and RPC:
  - public RPC
  - LCD or REST
  - gRPC
  - websocket

Indexers and explorers:
  - Mintscan, Big Dipper, internal explorer

Relayers:
  - Hermes or Go Relayer instances

Storage and DNS:
  - databases
  - snapshots
  - subdomains

Archive before shutdown

Bash

tar -czf chain-archive-final-$(date +%Y%m%d).tar.gz ~/.chain/
aws s3 cp chain-archive-final-*.tar.gz s3://your-archive-bucket/

chaind export --height=HALT_HEIGHT > final_state_archive.json
gzip final_state_archive.json
aws s3 cp final_state_archive.json.gz s3://your-archive-bucket/

These archives matter for legal support, user disputes, treasury auditability, and historical verification.

Decommissioning sequence

Stop relayers.
Halt validators and export final state.
Keep read-only RPC or LCD services alive long enough for users and explorers to query history.
Redirect old application domains to the new Solana product.
Move old infrastructure to an explicit archive or retirement state instead of silently killing it.

Registry and DNS cleanup

Update chain-registry and public docs to mark the chain as retired.
Notify relayer operators and counterparties.
Redirect or retire old RPC, LCD, and application domains on a known schedule.
Mark old token identifiers as deprecated in market-data surfaces where possible.

11. Full Migration Checklist

Decision and planning

Align internally on destination chain, migration scope, and halt window.
Complete legal review and asset inventory.
Classify contracts and modules as migrate, replace, or deprecate.
Audit IBC channels, relayers, counterparties, validators, and exchange dependencies.

Community and communication

Publish a forum rationale before the binding governance action.
Coordinate exchanges, validators, relayers, and counterparties before the public rush.
Publish a repeated reminder schedule with exact dates and heights.

Cosmos shutdown

Set and verify the halt height across validators.
Pause relayers and unwind IBC where needed.
Export final state and derive the canonical balance and entitlement ledgers.
Archive node data and state artifacts to durable storage.

SPL launch and migration mechanics

Create the token mint, metadata, treasury accounts, and multisig control plane.
Choose the migration architecture: snapshot plus airdrop, one-way bridge, or supported third-party bridge.
Define the unclaimed-token policy before launch.
Deploy and rehearse the claim or bridge programs.

Governance migration

Create the new Realm, council, and governed treasury accounts before handing over critical authorities.
Move mint authority, freeze authority, treasury control, and program upgrade authority into the chosen governance system.
Decide which actions require token voting, council approval, or multisig execution during the transition period.

Programs and product migration

Recreate stateful obligations such as vesting, escrow, and rewards intentionally.
Rewrite the frontend and support tooling for Solana wallets and transaction semantics.

Post-migration operations

Monitor claim completion rate and support queues.
Publish a post-migration report with totals, deadlines, and leftover policy.
Retire or archive remaining Cosmos infrastructure on a public schedule.

12. Learn from other teams

What worked in prior migrations

One-way migration windows with a public deadline and exchange coordination created urgency and high completion rates.
Public request-for-proposal or evaluation processes gave the community a real decision framework instead of a hand-wavy announcement.
Long notice periods of 60 to 90 days reduced stranded balances and support chaos.
Archiving chain state preserved auditability and historical support data.

What failed

Short notice windows stranded meaningful supply.
Skipping exchange coordination left custodial users behind.
Teams that failed to archive state lost an authoritative record of balances and protocol history.

Treat this as a coordinated shutdown and relaunch.

Plan the shutdown before the rewrite

Separate token migration from product migration

Launch on Solana like a production cutover

1. Why Solana Is a Good Fit

Architecture differences: Cosmos app chains vs Solana

2. Phase 0: Planning & Announcement

Internal alignment

Community governance

Recommended timeline

3. Phase 1: Cosmos Chain Shutdown (Technical)

Set the halt block height

Export final state

Compute the canonical snapshot

Handle IBC channels

Validator offboarding

4. Phase 2: Token Migration Architecture

Recommended architecture: Merkle tree claimer

What the Solana claimer should own

Why this architecture is usually better

Unclaimed token policy

5. Address Linking

Recommended: pre-registration plus a carefully scoped fallback

Example: preregistration record

6. Phase 3: Launching on Solana

Create the SPL token

Add metadata

Mint supply and lock authorities deliberately

Multisig, token lists, and liquidity

7. Phase 4: Smart Contract / Program Migration

Categorize every contract and module

Vesting migration

NFT migration

DeFi positions

What usually does not migrate 1:1

Solana constraints to plan around

8. Phase 5: Governance Migration

Realms vs. Squads

How to migrate governance cleanly

Practical mapping

9. Phase 6: User Migration & Communication

Communication plan

Migration portal requirements

Exchange coordination

10. Phase 7: Decommissioning Cosmos Infrastructure

Inventory everything first

Archive before shutdown

Decommissioning sequence

Registry and DNS cleanup

11. Full Migration Checklist

Decision and planning

Community and communication

Cosmos shutdown

SPL launch and migration mechanics

Governance migration

Programs and product migration

Post-migration operations

12. Learn from other teams

What worked in prior migrations

What failed

References for migration operators

Merkle Tree Token Claimer

Realms Governance

Squads Protocol