Wallet & frontend integration

The Stellaroid Earn frontend is a Next.js 15 (App Router) + React 19 app that uses @stellar/stellar-sdk to build and submit Soroban transactions, @stellar/freighter-api for the Freighter browser extension, and @albedo-link/intent for the Albedo web wallet. This page condenses the integration into its three layers and the code patterns you need to extend it.

Architecture

The integration is layered so the UI never talks to a specific wallet SDK or to process.env directly:

• Config layer (frontend/src/lib/config.ts) — reads all NEXT_PUBLIC_* env vars once into a single appConfig object, maps network names to canonical passphrases, and exposes guards like hasRequiredConfig().
• Wallet provider layer (frontend/src/lib/wallet/) — a registry of providers behind one three-method interface (read, connect, sign). Two providers ship today: Freighter (desktop browser extension) and Albedo (web wallet that also works on mobile). The active provider id is persisted in localStorage so sessions survive reloads.
• Contract client (frontend/src/lib/contract-client.ts) — builds transactions with @stellar/stellar-sdk. Reads run as signature-free simulations sourced from a read-only address; writes are prepared by the RPC, signed by the active wallet, submitted, and polled to confirmation.
• UI layer (components/, hooks/) — everything touching a wallet is marked "use client", because both wallet SDKs are browser-only APIs that cannot run in Server Components.

npm add @stellar/stellar-sdk @stellar/freighter-api @albedo-link/intent

Config layer: environment variables

All configuration is public (NEXT_PUBLIC_*), read in one place, and defaulted to testnet values. hasRequiredConfig() requires contractId and rpcUrl; the contract client throws early with a clear message when they are missing.

getExpectedNetworkPassphrase() resolves the network name to the canonical SDK passphrase (Networks.TESTNET / Networks.PUBLIC) and falls back to the configured passphrase for unrecognized names. Every transaction the app builds or signs uses this expected passphrase.

Wallet provider layer

The wallet layer is no longer Freighter-only. frontend/src/lib/wallet/index.ts keeps a registry of providers (PROVIDERS = [freighterProvider, albedoProvider] — order is display priority in the picker), each implementing the same interface from frontend/src/lib/wallet/types.ts:

export type WalletProviderId = "freighter" | "albedo";

// "extension" wallets need a desktop browser extension; "web" wallets run in
// any browser (including mobile) via a popup/redirect and need no install.
export type WalletProviderKind = "extension" | "web";

export interface WalletProviderModule extends WalletProviderMeta {
  /** Read the current connection without prompting the user. */
  read(): Promise<WalletSnapshot>;
  /** Prompt the user to connect; resolves to a connected snapshot or throws. */
  connect(): Promise<WalletSnapshot>;
  /** Sign a transaction XDR for `address`; resolves to the signed XDR. */
  sign(xdr: string, address: string): Promise<string>;
}

The active provider id is persisted under the localStorage key stellaroid:wallet-provider, so readWallet() can restore a session on page load without prompting. disconnectWallet() is local-only: it clears that key (and Albedo's cached address) but does not revoke any permissions inside the wallet itself. In e2e mode the whole layer is bypassed with a fixed test address so headless tests never need an extension or popup.

Contract client: reads vs writes

The contract client has two interaction modes with very different requirements:

Because reads need no wallet, anonymous visitors can query contract state (issuers, certificates, opportunities) without connecting anything — the funded read address exists purely because simulateTransaction requires a valid on-chain source account.

The shipped client also carries raw JSON-RPC fallbacks: when the SDK's XDR parser throws Bad union switch on newer RPC response arms, simulation, submission, and polling each retry over plain fetch JSON-RPC calls instead of failing the whole operation.

Key code patterns

Detecting and connecting a wallet

UI code talks only to the public API of @/lib/wallet — never to a specific wallet SDK:

"use client";

import { connectWallet, listProviders, readWallet } from "@/lib/wallet";

// Enumerate wallets for the picker UI (registry order = display priority)
const providers = listProviders();
// [{ id: "freighter", kind: "extension", label: "Freighter", ... },
//  { id: "albedo",    kind: "web",       label: "Albedo", ... }]

// Restore an existing session on mount, without prompting
const existing = await readWallet();

// Prompt the user to connect a specific provider
const snapshot = await connectWallet("albedo");
if (snapshot.status === "connected") {
  // snapshot.address, snapshot.provider, snapshot.isExpectedNetwork
}

Network check

The Freighter provider compares the wallet's reported network against the app's expected one, accepting a match by either passphrase or network name, and the UI gates every write behind the result:

const networkPassphrase =
  networkResponse.networkPassphrase || getExpectedNetworkPassphrase();

// Accept a match by either passphrase or network name
const isExpectedNetwork =
  networkPassphrase === getExpectedNetworkPassphrase() ||
  networkResponse.network === appConfig.network;

// Gate all contract writes behind this flag in the UI
const actionsBlocked =
  wallet.status !== "connected" || !wallet.address || !wallet.isExpectedNetwork;

Read-only call (simulate)

const simulation = await server.simulateTransaction(transaction);

if (rpc.Api.isSimulationError(simulation)) {
  throw new Error(normalizeError(simulation.error));
}

// Decode the XDR return value, then normalize to app types
return transform(scValToNative(simulation.result.retval));

Write call (sign and submit)

Writes follow a five-step shape. Note that signing goes through the wallet layer's signTransaction — whichever provider the user connected handles the actual prompt:

import { signTransaction as signWithWallet } from "@/lib/wallet";

// 1. Build the invocation against the source account's sequence number
const transaction = await buildTransaction(sourceAddress, method, args);

// 2. Prepare: RPC simulation attaches the Soroban footprint and resource fee
const prepared = await server.prepareTransaction(transaction);

// 3. Sign with the active wallet (Freighter popup or Albedo redirect)
const signedXdr = await signWithWallet(prepared.toXDR(), sourceAddress);
const signed = TransactionBuilder.fromXDR(
  signedXdr,
  getExpectedNetworkPassphrase(),
);

// 4. Submit
const sendResponse = await server.sendTransaction(signed);

// 5. Poll until confirmed or failed
const final = await server.pollTransaction(sendResponse.hash, {
  attempts: 20,
  sleepStrategy: () => 1200, // 1.2 s between polls
});

The production client accepts both PENDING and DUPLICATE submission statuses, and treats a FAILED or NOT_FOUND poll result as an error surfaced through a normalizer that maps Soroban's numeric error codes (#1, #2, ...) to human-readable messages matching the contract's Rust contracterror enum.

Common pitfalls

Further reading

The full step-by-step guide — including argument serialization with nativeToScVal, return-value normalizers, error mapping, amount formatting helpers, and complete data-flow walkthroughs — lives in the repo at docs/reference/freighter-integration.md and is the canonical spec for this integration.