@echomirror/stellar

Production-ready Stellar integration for the EchoMirror SDK: multi-wallet support (Freighter, xBull, Albedo), a full transaction builder (payments, trustlines, path payments, fee-bumps), a typed error taxonomy, and automatic retry with backoff for transient Horizon failures.

npm install @echomirror/stellar

Quickstart

import { StellarClient, connectWallet } from '@echomirror/stellar'

const stellar = new StellarClient({ network: 'testnet' })

// Auto-detects Freighter → xBull → Albedo, with install guidance if none exist
const { adapter, connection } = await connectWallet({ network: 'testnet' })

const tx = await stellar.buildPaymentTransaction({
  source: connection.publicKey,
  destination: 'G…',
  amount: '12.5',
  memo: 'thanks! ✨',
})

// Wallet signs (popup/extension), SDK submits with retry on transient failures
const result = await stellar.signAndSubmit(adapter, tx)
console.log('on-chain:', result.hash)

Server-side (Node) there is no wallet — sign with a Keypair:

import { Keypair, StellarClient } from '@echomirror/stellar'

const stellar = new StellarClient({ network: 'testnet' })
const tx = await stellar.buildPaymentTransaction({ source: kp.publicKey(), destination, amount: '5' })
tx.sign(kp)
await stellar.submitTransaction(tx)

Which wallet method for which use case?

Use case	Call	Notes
"Connect wallet" button, no preference	connectWallet()	Tries Freighter → xBull → Albedo; Albedo works in any browser (popup), so it is the universal fallback
Let the user pick a wallet	detectWallets() → render list → adapter.connect()	Only returns wallets usable right now
Force one specific wallet	getWalletAdapter('freighter' | 'xbull' | 'albedo')	Throws typed WalletNotFoundError (with install URL) if unavailable
Sign a transaction you built	stellar.signAndSubmit(adapter, tx)	Or adapter.signTransaction(xdr, { networkPassphrase }) if you submit yourself
Detect which network the user's wallet is on	adapter.connect() → connection.network	Only Freighter exposes its own network selection; xBull/Albedo use the network you pass to connectWallet/the adapter constructor
No browser (Node/server)	none — sign with Keypair, then stellar.submitTransaction(signedXdr)	connectWallet() throws a WalletNotFoundError explaining this
Legacy EchoMirror API flows (ECHO token)	sendEcho, getBalance, …	Unchanged signatures; sendEcho now signs with any available wallet, not just Freighter

Which transaction builder for which use case?

Use case	Call
Send XLM or an issued asset	buildPaymentTransaction({ source, destination, amount, asset? })
Send XLM to a brand-new (unfunded) account	buildPaymentTransaction({ …, createDestination: true }) — becomes a createAccount op
Let an account hold a new asset	buildTrustlineTransaction({ source, asset, limit? })
Gift asset B while paying in asset A (exact spend)	buildPathPaymentStrictSend({ sendAsset, sendAmount, destAsset, … })
Deliver an exact amount of asset B (capped spend)	buildPathPaymentStrictReceive({ sendAsset, destAsset, destAmount, … })
Quote a conversion before committing	findPaymentPath({ type, … })
Sponsor someone else's transaction fee	buildFeeBumpTransaction({ feeSource, innerTransaction })

Path payments quote Horizon automatically when you omit path/destMin/sendMax and protect you with a slippage bound (slippageBps, default 0.5%).

By default builders preflight: they check the destination exists, the trustline is in place, and the source's spendable XLM (balance minus base reserve and liabilities) covers the amount — so users never sign a doomed transaction. Pass preflight: false to skip the extra Horizon calls.

Error taxonomy

Every failure throws a StellarSdkError subclass with a machine-readable code and an actionable message. error.retryable tells you if resubmitting can ever succeed:

Code	Class	Retryable	Typical cause
WALLET_NOT_FOUND	WalletNotFoundError	no	Extension not installed / Node environment
WALLET_USER_REJECTED	WalletUserRejectedError	no	User dismissed the wallet popup
WALLET_CONNECTION_FAILED	WalletConnectionError	no	Any other wallet failure
ACCOUNT_NOT_FOUND / DESTINATION_NOT_FOUND	AccountNotFoundError	no	Account not funded on this network
INSUFFICIENT_BALANCE	InsufficientBalanceError	no	op_underfunded, op_low_reserve, fee > balance
TRUSTLINE_MISSING	TrustlineMissingError	no	op_no_trust, op_src_no_trust, op_no_issuer
TRUSTLINE_LIMIT_EXCEEDED	TrustlineLimitExceededError	no	op_line_full
PATH_NOT_FOUND	PathNotFoundError	no	No liquidity / price moved beyond slippage
TX_BAD_SEQUENCE	BadSequenceError	no — rebuild	Stale sequence number
TX_EXPIRED	TransactionExpiredError	no — rebuild	Time bounds passed
TX_INSUFFICIENT_FEE	InsufficientFeeError	no — rebuild or fee-bump	Surge pricing
TX_MALFORMED	TransactionMalformedError	no	Bad envelope / signatures / inputs
TX_FAILED	TransactionFailedError	no	Any other operation failure (codes attached)
NETWORK_TIMEOUT	HorizonTimeoutError	yes	Horizon 504 — identical resubmit is hash-idempotent
RATE_LIMITED	HorizonRateLimitError	yes	Horizon 429 (honours Retry-After)
HORIZON_UNAVAILABLE	HorizonUnavailableError	yes	5xx / network unreachable

submitTransaction retries only the retryable class automatically (full-jitter exponential backoff, 3 retries by default — tune via new StellarClient({ retry: { … } })). Permanent failures are never retried: resubmitting a tx_bad_seq or op_underfunded envelope cannot succeed. Resubmitting after a timeout is safe because Horizon dedupes by transaction hash and returns the original result.

Testing

npm test                    # unit tests, offline, mocked Horizon/wallets
npm run test:integration    # live Stellar testnet: Friendbot-funded accounts,
                            # every tx type, on-chain assertions, real error mapping
npm run test:e2e            # real Freighter extension in Chromium via Playwright:
                            # onboarding → testnet → connect popup → sign popup →
                            # payment asserted on-chain

The e2e run downloads the Freighter extension from the Chrome Web Store on first use (node e2e/scripts/fetch-freighter.mjs) and drives its actual UI. Selectors live in one place (e2e/helpers.ts) and are pinned to Freighter's data-testids.

In CI, the unit suite runs on every PR via js-ci.yml. The two suites that need live external infrastructure — the public testnet and the real Freighter extension — run nightly and on demand via .github/workflows/stellar-live.yml, following the same convention as sync-live-testnet.yml.

Note: modern Freighter does not inject window.freighterApi — pages must use @stellar/freighter-api (postMessage). The FreighterAdapter handles both, preferring an injected global when present (old versions, tests) and falling back to the npm package (real browsers today).