Installing and enabling Solana

Solana is enabled in five 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

• A working Bicrypto install — backend, frontend and cron under PM2
• Ecosystem installed, enabled and working
• The Ecosystem vault unlocked — /admin/ecosystem shows a green Vault Active badge
• A purchased Solana licence (Envato item 54514052) activated on this install
• The chain service present at backend/src/blockchains/sol.ts
• Shell access to the project root, to edit .env and restart PM2
• SOL to fund the master wallet, on the cluster you are about to configure

1. Activate the licence

Activation writes lic/54514052.lic under the project root — an encrypted, machine-bound file. Two independent code paths check for it: the admin toggle refuses to enable the chain without it, and the Solana service checks it again at construction.

The result of the service-side check is cached for five minutes. If you activate the licence while the backend is running, allow for that delay before concluding it did not work.

2. Enable the chain row

Admin → Ecosystem → Blockchains lists the four licensed chains with their product IDs. The Solana row is seeded by 20240402234742-ecosystemBlockchains.js as Solana Blockchain for Ecosystem Addon, product ID 54514052, with status: false.

Enabling the row is what makes SOL appear as a choice in the token and master wallet screens — the blockchain options endpoint adds Solana to its list only when this row exists and is enabled.

3. 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.

4. 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.

5. 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.

6. 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.

7. Add tokens

Admin → Ecosystem → Tokens. Solana appears in the chain list once step 2 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.

8. 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