Running Solana

Solana is chain id 1399811149 in this platform, virtual machine SVM, one aggregator (Jupiter), and the newest surface in the addon. Everything an operator already knows about the EVM path is nearly true here, and the four places it is not are the four places a Solana install goes quietly wrong.

Before anything else: the RPC endpoint

Resolution mirrors the EVM ladder exactly, so there is one rule to learn:

1. dexChain.rpcUrlOverride — the row, set on Admin → Swap → Chains
2. APP_DEX_RPC_SOLANA — this addon's own variable
3. SOL_MAINNET_RPC — the ecosystem's, so a chain you already scan for deposits needs no new variable

Reads use the confirmed commitment; settlement uses finalized. That asymmetry is the same one EVM expresses as requiredConfirmations: reading is cheap and can be redone, settling is not.

The four assumptions Solana breaks

1. There is no confirmation depth

headBlock - blockNumber >= requiredConfirmations is the EVM rule, and it has no Solana equivalent. A slot is finalized or it is not — finality is a supermajority vote, not an accumulation of work.

Rather than forking the shared decision function, the observation synthesises the number that function already knows how to read: a finalized transaction reports headBlock = slot + requiredConfirmations, which satisfies the depth test by construction. One place reconciles the two models, and it does so by producing the EVM shape.

Two consequences on screen:

• dexChain.requiredConfirmations on the Solana row means nothing. It is set to 1 because the column is NOT NULL; every SVM path ignores it in favour of the finalized commitment. Raising it does not make settlement safer.
• confirmations on a Solana swap row is not a count of anything. Solana's own confirmations === null is how it says rooted — finalized and no longer counted. Reading that null as zero is how a finalized transaction would never confirm, which is why the observation treats it as final.

2. Slots are not block numbers

Solana skips slots: a slot whose leader produces nothing produces no block. So slot numbers are not contiguous, and the difference between two slots is not a count of blocks.

Anything computing "how far behind are we" from a slot delta is computing a number with no meaning. If you need lag on Solana, use timestamps. This is exactly why the confirmation depth above is synthesised from the finality answer rather than measured from a slot arithmetic.

3. The drop rule has no nonce to work with

EVM decides a transaction is gone by comparing the sender's current nonce against the transaction's. Solana has no account nonce — replay protection is the recent blockhash, and a transaction becomes permanently invalid the moment lastValidBlockHeight passes.

That is a better signal than the heuristic it replaces, and the sweeper is built to use it: lastValidBlockHeight is stamped on the quote's raw payload by the Jupiter adapter, and expiry is mapped onto the nonce pair so the shared decision function needs no SVM branch.

The visible result on Admin → Swap → Activity → Swaps:

• An unseen Solana row is DROPPED with reason not-seen, not nonce-consumed, and only once it is older than dexDropAfterMs.
• The 30-minute drop window governs Solana too, exactly as it governs TRON and TON. Do not tell a customer that an expired swap will be marked dropped on the next sweep — it waits out the window like every other chain the sweeper has no nonce for.
• Replacement is refused outright. REPLACED is a nonce mechanic; there is no equivalent, so a Solana row never reaches that state.

See Swap history for the full state machine.

4. A failure is an err object, not status: 0

There is no status: 1 | 0 on a Solana result. There is an err field that is null on success.

Non-null means the transaction was included and its instructions failed. That is the same thing an EVM status: 0 receipt means, the user paid for it either way, and it is charged for identically — the row becomes REVERTED with reason reverted. It is emphatically not "not found", and a support answer that treats it as one will tell a customer their swap never happened when it did and cost them.

One trap worth knowing because it fails silently: fetching the full transaction requires maxSupportedTransactionVersion: 0. Without it, getTransaction returns null for every versioned transaction rather than erroring — and every Jupiter swap is versioned, because the route needs address lookup tables to fit inside Solana's 1232-byte limit. The symptom would be swaps that finalize and then look as though they were never seen.

And a fifth: there are no receipt logs

There is no logs array of {topics, data}. The equivalent is preTokenBalances / postTokenBalances — token balance deltas, which are a better source for fee attribution than EVM logs, because they are the net effect rather than the events a contract claimed.

The observation collects both arrays and hands them to the accrual writer.

Network fee is recorded the same way: the flat lamport fee goes into gasUsed and effectiveGasPrice is left null, precisely so nothing multiplies two figures into a fee that was never charged. Solana charges per signature plus a priority bid, not gas × price.

The fee account, in the detail an operator needs

The concept is covered on Wallets and Providers. This is the mechanism.

One account per (owner, mint)

An SPL token cannot be held by a wallet. It is held by an Associated Token Account the wallet owns, and there is exactly one canonical such account per (owner, mint) pair. So on Solana:

• dexChain.feeRecipient stores the owner wallet.
• Every mint fees can arrive in needs its own account under that wallet.
• Each account must exist before anything can arrive, and creating one costs rent — about 0.00204 SOL, refundable if the account is ever closed.

The address is derived, never stored. An ATA is a program-derived address: given the owner and the mint there is exactly one answer, computable offline. Storing it would create a second source of truth that can disagree with the chain, and the disagreement would send fees wherever the stale row said.

The derivation is done with allowOwnerOffCurve: true on purpose. An owner that is a PDA — a multisig or a program-controlled treasury, which is what a careful operator uses — is off the ed25519 curve, and the default derivation throws for those. Refusing to derive for a multisig treasury would push operators toward a bare keypair, which is the less safe choice.

Jupiter takes the token account, not the wallet

Jupiter's feeAccount parameter wants the token account. Passing a wallet address is rejected; passing an account that does not exist yet is worse, because some route shapes accept it and silently drop the fee.

Jupiter also requires platformFeeBps and feeAccount together — sending the bps without the account is not a partial success. So the adapter decides once and records the decision on the quote:

• The fee applies only when the quote is not price-only, feeBps > 0, and an account address was resolved.
• When it cannot be resolved, the quote is served at zero fee. The adapter names the reason as feeAccountMissingReason, but only on its in-memory raw payload — and nothing persists that payload on a Solana route, because dexQuote.routeSummary is written by no code path and complianceSnapshot carries raw (as poolState) only for a direct-pool route, which a Jupiter quote is not. No column records why the fee was dropped. The row's feeBps keeps the configured rate either way, so it cannot tell you; the field that moves is feeSide, which the adapter leaves null when the fee did not apply. See The quote log.
• An unreachable RPC counts as unresolved. We cannot prove the account exists, and sending an unverified account would convert a transient outage into revenue that looks collected and is not.

The mint that matters is the buy-side one: Jupiter takes platformFeeBps from the output mint on an exact-in swap, so the account you need is for the token the user receives.

Building the creation transaction

Body: chainId, mint (base58, case-significant), payer.

Nothing is signed server-side. The server produces bytes and a wallet the operator controls signs them — the same contract every other write in this addon follows, and the reason this route can exist at all without breaking the non-custody guarantee.

Four refusals, each named:

• An EVM chain — its fee recipient receives every token with no setup, and returning an empty success would leave you waiting for a transaction that is never coming.
• An invalid mint or payer address.
• No fee recipient set for the chain, so there is no wallet to create the account under.
• A mint that is not in the chain's token list — a fee account for a token nobody can swap collects nothing.

The response carries transaction (base64, unsigned, v0), feeAccount, lastValidBlockHeight, owner, mint and symbol.

Payer and owner may differ, deliberately. A treasury owned by a multisig cannot pay for its own account creation without the multisig executing a transaction. The operator clicking this funds the rent; the multisig owns the result. Refusing that would push operators toward a bare keypair treasury.

It is built as a v0 transaction even though one instruction would fit in a legacy one — the client has exactly one deserialise-and-sign routine, and a legacy transaction arriving at a VersionedTransaction.deserialize call fails in a way that reads as a corrupt payload.

Why getOrCreateAssociatedTokenAccount is a lint error here

It is banned in this tree, along with createMint and mintTo, by both guards — the eslint config and the build-time invariant check. mintToChecked is on the eslint rule's import list too, but the invariant script's pattern is \b(createMint|mintTo|getOrCreateAssociatedTokenAccount)\b, and the word boundary after mintTo cannot match the longer name — so that one identifier trips only one of the two guards.

The reason is one sentence: it SPENDS to create the account, which means some key paid for it, which means some key was held here. This addon holds no key for anybody, and that is enforced rather than intended.

The permitted pair is getAssociatedTokenAddressSync — derives the same address with no signer and no lamports — and createAssociatedTokenAccountInstruction, which builds an instruction somebody else signs. The whole ecosystem Solana service (@b/blockchains/sol) is forbidden for the same reason: it creates wallets, deploys SPL tokens, mints supply and decrypts a master wallet to sign withdrawals. The DEX addon's own read handle exists so that forbidden import has somewhere legitimate to go.

Gas reserve: it is rent, not gas

Solana's minGasReserve is 0.01 SOL, an order of magnitude above what the transaction fee needs, and the excess is deliberate.

A signature costs 5000 lamports plus a priority bid that spikes under load. What dominates is rent exemption: buying a token the user has never held creates an associated token account for them, and an account must hold ~0.00204 SOL to exist at all. A Jupiter route can create more than one. Reserving only the fee would let a user spend to the last lamport and then watch the swap fail because the destination account cannot be created — with the fee already paid.

The routine