Environment and reference
Every variable the Solana chain module reads, the ones that only affect metadata, the ones read by nothing, plus the chain registry values, database rows and admin endpoints this product touches.
Everything on this page is read from the project root .env, the database, or
the chain registry. None of the Solana variables appear in .env.example, so on
a fresh install every one of them is unset until you add it.
Ecosystem's own environment reference covers the vault, ScyllaDB and every other chain. This page covers only what Solana touches.
Solana variables
SolanaService in backend/src/blockchains/sol.ts resolves the cluster from
SOL_NETWORK alone — "mainnet" becomes mainnet-beta, "testnet" becomes
testnet, and every other value falls through to devnet — then builds its
endpoint pool from SOL_<RESOLVED>_RPC, falling back to the public cluster URL
when that key is unset.
So SOL_NETWORK="mainnet-beta" costs twice. It looks like the correct cluster
name, it is not one of the two accepted values, and nothing logs the
fall-through in the request path: the install runs on devnet while every screen
looks healthy, and the paid endpoint you put in SOL_MAINNET_RPC is in a key
nothing reads.
The requirements report names the key for the resolved cluster and whether it is set, which is the fastest way to confirm which one is actually in play.
If the Swap addon is present it reads these keys too: resolveServerRpc in
dex/utils/chains.ts takes SOL_<NETWORK>_RPC as the last rung of its RPC
ladder, under the chain row's override and APP_DEX_RPC_SOLANA. One endpoint
can therefore carry both this chain's traffic and Swap's.
Ecosystem variables that shape Solana behaviour
These are not Solana-specific, but Solana is the chain most likely to make you reach for them. See Network and RPC for when.
The vault variables — ENCRYPTED_ENCRYPTION_KEY and
ENCRYPTION_KEY_PASSPHRASE — are Ecosystem's, and every Solana private key on
the install depends on them. They are documented under
Master wallets and the vault; do not
edit either by hand.
Chain registry values
These are compiled into the platform, not configurable.
| Property | Value |
|---|---|
| Chain symbol | SOL |
| Display name | Solana |
| Native currency | SOL |
| Decimals | 9 |
| Token standard | SPL |
| Mainnet explorer | https://explorer.solana.com |
| Testnet explorer | https://explorer.solana.com?cluster=testnet |
| Devnet explorer | https://explorer.solana.com?cluster=devnet |
| Configured confirmation depth | none — pending Solana deposits are credited on the next verification pass |
| Custodial contracts | never; Solana is a non-custodial chain in Ecosystem's model |
| Network filtering of token rows | none; Solana is network-agnostic, so a token's network label is never checked |
Contract types behave as follows on this chain:
contractType |
Meaning on Solana |
|---|---|
NATIVE |
SOL itself. Deposits and withdrawals use the customer's own address, and the network fee comes out of the withdrawn balance |
PERMIT |
An SPL token. Deposits land in the customer's associated token account; withdrawals are signed by the customer with the master wallet as fee payer |
NO_PERMIT |
Ignored. The deposit path uses the customer's own address anyway rather than looking for a custodial contract that cannot exist here |
Where the data lives
| Record | What it holds |
|---|---|
ecosystem_blockchain |
The seeded Solana row: chain = "SOL", productId = "54514052", status — the enable toggle |
lic/54514052.lic |
The activated licence file, encrypted and machine-bound. Its presence is checked at the toggle and again at service construction, cached for five minutes |
ecosystem_master_wallet |
One row for chain = "SOL". data is the encrypted keypair blob and is the only persisted copy |
wallet.address |
JSON map on the ECO wallet. The SOL entry carries the address, the network label from SOLANA_NETWORK, and a display balance |
wallet_data |
One row per wallet on chain = "SOL", holding the encrypted mnemonic, derivation path and secret key. index is always 0 on this chain and is not a derivation index |
ecosystem_token |
The token definition. On Solana, contract is the SPL mint address and is used verbatim to build deposit subscriptions |
transaction |
Deposits and withdrawals. trxId is the Solana transaction signature |
Admin endpoints
Every one of these is an Ecosystem endpoint that Solana participates in; there are no Solana-only routes.
GET /api/admin/ecosystem/wallet/master/balance carries its own copy of the
balance refresh, and that copy knows about UTXO chains and getProvider() and
nothing else. getProvider() builds an ethers JSON-RPC provider from
chainConfigs, and it cannot produce one for SOL at all: it wants a
SOL_<NETWORK>_RPC variable and then a chainId, and the SOL entry carries
explorer URLs and no chainId. Which of the two errors you find in the log
depends only on how far it got — on a normal install, where no SOL_*_RPC is set
because nothing on this chain reads one, it throws first on the missing variable,
"Environment variable SOL_MAINNET_RPC is not set"; set that variable and it
reaches the second, "Chain ID not found for SOL on mainnet". Either way the error
is caught, logged to the console, and the row keeps its old balance. The Solana
branch — and the one-minute cache — live in getEcosystemMasterWalletBalance,
which only the list route calls.
The token-holders view is worse, because it has no working version at all.
fetchTokenHolders in ecosystem/utils/tokens.ts builds one URL shape for every
chain: https://<registry explorer>/api?module=account&action=tokentx&…, which is
the Etherscan family's API. The registry explorer value for SOL is already a
full URL, https://explorer.solana.com, so the string it fetches begins
https://https:// — the request is malformed before it is even pointed at an API
Solana does not serve. Expect a 500 reading "Failed to fetch token holders", or,
if you have set no SOL_EXPLORER_API_KEY or ETHERSCAN_API_KEY, an earlier 500
complaining about the missing key. No configuration fixes either one; read
holders from a Solana explorer or an indexer instead.
Permission keys follow the platform-wide convention and are granted per role. See Ecosystem: admin console for the full permission list and where each screen lives.
Related
- Network and RPC — what the cluster variables actually do
- Install and enable — the order these are set in
- Troubleshooting — symptom-first diagnosis