Installing and enabling Solana

Solana is enabled in six steps, and the order matters more than usual. Deposit addresses are generated against whatever cluster is configured at the time, and the stored wallet record stamps a network name that nothing later corrects. Set the cluster before anyone can reach a deposit page, not after.

Nothing here is done by installer.sh or by the Ecosystem installer. Every step is manual.

Before you begin

1. Activate the licence

Go to Admin → System → Extension Manager (/admin/system/extension) — the page heading is Add-ons & Integrations. On the Blockchains tab (or by searching for Solana) find the Solana Blockchain for Ecosystem Addon card, product ID 54514052, and click it. Until its licence is activated the card reads Activate and its enable switch is disabled — the tooltip says Activate license first.

On the product page press Activate License. Paste the purchase code from your MashDiv dashboard, optionally an email address for update notifications, and press Activate License. The screen confirms License Activated! and returns you to the product page a couple of seconds later. If the server has no outbound access, use the License File tab on the same screen instead: download the licence certificate from your MashDiv dashboard, place it as license.txt in the /lic folder at the project root, and press the button on that tab.

Activation is what writes the machine-bound licence file lic/54514052.lic under the project root. The Solana chain service checks that licence again at construction and caches the result for five minutes — if you activate while the backend is running, allow for that delay before concluding it did not work. The restart in step 5 clears it either way.

2. Install the release

Back on the product page, now licensed, the Overview tab has a release panel. If it offers Install v…, press it; if it says Up to date on a licence you have only just activated, press Check for Updates once, then install whatever it offers. The Releases tab holds the notes for the version you are being offered — read them first.

Install downloads the release, verifies it and extracts it over the project root — this is what puts the chain service at backend/src/blockchains/sol.ts, the file the diagnostics in step 6 check for. It runs no migrations, builds nothing and restarts nothing, so finish it from a shell on the server:

pnpm updator

That is the finalise chain — stop, dependencies, schema, seed data, frontend build, start. If the panel still says Up to date after the check there is nothing to download — the release already on the server is current — and you move straight on to the next step.

3. Switch the chain on

Turn the Enabled switch on — in the product page heading, or on the Solana card on the Blockchains tab of the Extension Manager, usable now that the licence is verified. Enabling the chain is what makes SOL appear as a choice in the token and master wallet screens — the blockchain options endpoint offers Solana only while the chain is enabled.

A blockchain add-on switches a chain on for the Ecosystem addon: Ecosystem itself must be licensed and enabled before this switch does anything useful, which is why it sits in the checklist above.

The switch takes effect without a restart. The chain service does not — it is constructed from process.env when the backend starts, which is why steps 4 and 5 come before anyone touches a deposit page.

4. Set the cluster

Add SOL_NETWORK to the project root .env. It is not in .env.example, so on a fresh install it does not exist, and an absent value is the same as a wrong one.

# mainnet | testnet — anything else falls through to devnet
SOL_NETWORK="mainnet"

# Metadata only: stamped into each wallet's address record at generation time.
# Keep it equal to SOL_NETWORK.
SOLANA_NETWORK="mainnet"

SOLANA_NETWORK is a different variable and does not choose a cluster. It is written into the wallet's address record when an address is generated, and nothing else reads it. Setting the two to different values does not break deposits — it makes the stored record lie about which cluster the address belongs to, which is exactly the sort of thing that costs an afternoon during an incident.

For the full list including the variables that are read by nothing, see the environment reference.

5. Restart the backend

pm2 restart backend

The Solana connection is constructed once from process.env and held on a singleton, so an edited .env has no effect until the process restarts. A chain that "did not take" after an edit is almost always a chain that has not been restarted.

6. Run the diagnostics

Admin → Ecosystem → Blockchains → Requirements, select Solana, run the test.

The Solana test runs four checks and then reports readiness per flow:

Deposits and withdrawals are each reported ok only when the RPC health check passed and the licence and service checks passed. Withdrawals additionally fail if the vault is locked or the master wallet is missing or disabled — an RPC that answers is not a pass if a customer still cannot get their money out.

Read the cluster-resolution line specifically. It is the fastest way to catch a devnet fall-through, because it prints the endpoint the service will really use.

7. Create the master wallet

Admin → Ecosystem → Wallets → Master Wallets, create a wallet, choose SOL.

One per chain, enforced — a second attempt returns 409. The keypair is generated by the Solana service, so a missing or unlicensed service fails the creation outright rather than storing something unusable.

Then fund it with SOL. On Solana the master wallet is a fee payer, not a reserve. It pays for:

• the network fee on every SPL token withdrawal;
• creating an associated token account for a recipient who does not have one yet, which costs rent-exempt lamports;
• deploying an SPL mint and minting its initial supply.

Native SOL withdrawals do not touch it — they are signed by the customer's own address and the fee comes out of the balance being withdrawn. So an empty master wallet produces a selective failure: native SOL keeps working while every SPL withdrawal fails. See Wallets and key custody.

8. Add tokens

Admin → Ecosystem → Tokens. Solana appears in the chain list once step 3 is done.

Deploying creates the mint with the master wallet as mint authority and no freeze authority, at the decimals you specify. The initial supply is minted afterwards in the background — if that background mint fails after its retries, the token row is deleted again, so a token that vanishes shortly after creation is telling you the master wallet ran out of SOL.

To carry an existing token such as USDC, import it instead and set its contract to the SPL mint address. That address is used verbatim to build the deposit subscription, and an invalid one is rejected with an explicit log line naming the token rather than a silent dead monitor.

Set the token's network label to match your cluster even though nothing enforces it. Solana is on Ecosystem's network-agnostic list, so a devnet row is still offered on a mainnet install.

That estimate is the one place SOLANA_RPC_URL is read, and it defaults to mainnet-beta regardless of SOL_NETWORK. On a testnet or devnet install the figure is a mainnet number.

9. Verify end to end

Do this with your own money before a customer does it with theirs.

Related

• Network and RPC — what the public cluster costs you
• Wallets and key custody — keys, backups and the master wallet
• Troubleshooting — when one of the steps above did not take
• Ecosystem: Blockchains — the four chain families and how they differ