Smart Wallet Template

A Next.js 15 web frontend for interacting with any Stellar MCP server using PasskeyKit smart wallets and the OpenZeppelin Relayer for gasless transactions.

Setup

Clone and install


cd stellar-mcp/templates/smart-wallet
npm install
cp .env.example .env

Configure environment

Edit .env with your values (see Environment Variables below).

Run locally


npm run dev

Open http://localhost:3000 .

Deploy to Vercel


vercel deploy --prod

Set all environment variables in the Vercel dashboard before deploying.

Environment Variables

Variable	Required	Description
`NEXT_PUBLIC_MCP_SERVER_URL`	Yes	Browser-side URL to reach the MCP server. Defaults to `/mcp` (proxied by Next.js to avoid CORS).
`MCP_PROXY_TARGET`	Yes	Server-side target for the Next.js proxy. Point at your running MCP server.
`NEXT_PUBLIC_RPC_URL`	Yes	Soroban RPC endpoint
`NEXT_PUBLIC_NETWORK_PASSPHRASE`	Yes	Stellar network passphrase
`NEXT_PUBLIC_WALLET_WASM_HASH`	Yes	Smart wallet contract WASM hash
`NEXT_PUBLIC_RELAYER_URL`	Yes	OpenZeppelin Relayer URL
`NEXT_PUBLIC_RELAYER_API_KEY`	Yes	OpenZeppelin Relayer API key

Testnet defaults


NEXT_PUBLIC_MCP_SERVER_URL=/mcp
MCP_PROXY_TARGET=http://localhost:3000/mcp
NEXT_PUBLIC_RPC_URL=https://soroban-testnet.stellar.org
NEXT_PUBLIC_NETWORK_PASSPHRASE="Test SDF Network ; September 2015"
NEXT_PUBLIC_WALLET_WASM_HASH=b3eba29c256a2458faff84fc872226d29df37ad05a6a1c0efe2a95817d6765ec
NEXT_PUBLIC_RELAYER_URL=https://channels.openzeppelin.com/testnet
NEXT_PUBLIC_RELAYER_API_KEY=your-oz-relayer-api-key-here

Get a free testnet OZ Relayer API key at https://channels.openzeppelin.com/testnet/gen .

NEXT_PUBLIC_RELAYER_API_KEY is exposed to the browser. For production, use a server-side proxy to protect your key, or rate-limit at the relayer level.

Transaction Flow


User fills tool form
      ↓
client.simulate(toolName, args)   ← @stellar-mcp/client v0.2.0
      ↓                             returns { xdr, fee, simulationResult }
TransactionModal opens
  • Operation name
  • Arguments
  • Estimated fee (from simulate)   ← shown in green if available
  • OZ Relayer sponsorship note     ← shown if fee is null
      ↓
User clicks "Sign & Confirm"
      ↓
PasskeyKit WebAuthn prompt (biometric / security key)
      ↓
OZ Relayer sponsors + submits transaction
      ↓
Result shown (success toast + tx hash / error toast)

How simulate works

For write operations, useTransaction now calls client.simulate() instead of client.call(). The SDK’s simulate() method:

Calls the MCP server (which runs Soroban simulation server-side)
Extracts the estimated fee from the assembled XDR via extractFeeFromXdr
Returns { xdr, fee, simulationResult } — fee is in stroops

The TransactionModal converts stroops to XLM for display (e.g. 1000 stroops → 0.0001 XLM).

For read operations, client.call() is used directly (no fee needed).

Wallet Setup

On first visit, the app prompts the user to create or connect a smart wallet. The wallet is tied to the user’s device passkey (biometric or security key).

Create wallet — deploys a new smart wallet contract using NEXT_PUBLIC_WALLET_WASM_HASH
Connect wallet — reconnects an existing wallet by scanning for the passkey

The wallet contract ID is stored in localStorage and auto-reconnected on return visits.

Deploying Your Own WASM Hash

The testnet WASM hash b3eba29c256a2458faff84fc872226d29df37ad05a6a1c0efe2a95817d6765ec was built from the kalepail/passkey-kit next branch and is already deployed on testnet.

To deploy your own:


# Upload the wallet WASM
stellar contract upload \
  --wasm wallet.wasm \
  --source your-key \
  --network testnet

Set the returned hash in NEXT_PUBLIC_WALLET_WASM_HASH.

OZ Relayer Migration

This template uses passkey-kit v0.12.0 which replaced the deprecated Launchtube service with the OpenZeppelin Relayer.

Old (deprecated)	New
`LAUNCHTUBE_URL`	`NEXT_PUBLIC_RELAYER_URL`
`LAUNCHTUBE_JWT`	`NEXT_PUBLIC_RELAYER_API_KEY`
Launchtube endpoint	`https://channels.openzeppelin.com/testnet`

Stellar SDK Note

@stellar/stellar-sdk is pinned to ~14.4.0 in this template. Versions 14.6.1+ have a broken ../../package.json import in lib/minimal/bindings that breaks Next.js builds. The template includes a NormalModuleReplacementPlugin in next.config.ts to work around this.

Vercel Deployment

The template includes vercel.json. Deploy with:


vercel deploy --prod

Set all NEXT_PUBLIC_* variables in Vercel dashboard → Settings → Environment Variables. The Next.js proxy (MCP_PROXY_TARGET) is server-side and must also be set.

Smart Wallet Template

A Next.js 15 web frontend for interacting with any Stellar MCP server using PasskeyKit smart wallets and the OpenZeppelin Relayer for gasless transactions.

Setup

Clone and install


cd stellar-mcp/templates/smart-wallet
npm install
cp .env.example .env

Configure environment

Edit .env with your values (see Environment Variables below).

Run locally


npm run dev

Open http://localhost:3000 .

Deploy to Vercel


vercel deploy --prod

Set all environment variables in the Vercel dashboard before deploying.

Environment Variables

Variable	Required	Description
`NEXT_PUBLIC_MCP_SERVER_URL`	Yes	Browser-side URL to reach the MCP server. Defaults to `/mcp` (proxied by Next.js to avoid CORS).
`MCP_PROXY_TARGET`	Yes	Server-side target for the Next.js proxy. Point at your running MCP server.
`NEXT_PUBLIC_RPC_URL`	Yes	Soroban RPC endpoint
`NEXT_PUBLIC_NETWORK_PASSPHRASE`	Yes	Stellar network passphrase
`NEXT_PUBLIC_WALLET_WASM_HASH`	Yes	Smart wallet contract WASM hash
`NEXT_PUBLIC_RELAYER_URL`	Yes	OpenZeppelin Relayer URL
`NEXT_PUBLIC_RELAYER_API_KEY`	Yes	OpenZeppelin Relayer API key

Testnet defaults


NEXT_PUBLIC_MCP_SERVER_URL=/mcp
MCP_PROXY_TARGET=http://localhost:3000/mcp
NEXT_PUBLIC_RPC_URL=https://soroban-testnet.stellar.org
NEXT_PUBLIC_NETWORK_PASSPHRASE="Test SDF Network ; September 2015"
NEXT_PUBLIC_WALLET_WASM_HASH=b3eba29c256a2458faff84fc872226d29df37ad05a6a1c0efe2a95817d6765ec
NEXT_PUBLIC_RELAYER_URL=https://channels.openzeppelin.com/testnet
NEXT_PUBLIC_RELAYER_API_KEY=your-oz-relayer-api-key-here

Get a free testnet OZ Relayer API key at https://channels.openzeppelin.com/testnet/gen .

NEXT_PUBLIC_RELAYER_API_KEY is exposed to the browser. For production, use a server-side proxy to protect your key, or rate-limit at the relayer level.

Transaction Flow


User fills tool form
      ↓
client.simulate(toolName, args)   ← @stellar-mcp/client v0.2.0
      ↓                             returns { xdr, fee, simulationResult }
TransactionModal opens
  • Operation name
  • Arguments
  • Estimated fee (from simulate)   ← shown in green if available
  • OZ Relayer sponsorship note     ← shown if fee is null
      ↓
User clicks "Sign & Confirm"
      ↓
PasskeyKit WebAuthn prompt (biometric / security key)
      ↓
OZ Relayer sponsors + submits transaction
      ↓
Result shown (success toast + tx hash / error toast)

How simulate works

For write operations, useTransaction now calls client.simulate() instead of client.call(). The SDK’s simulate() method:

Calls the MCP server (which runs Soroban simulation server-side)
Extracts the estimated fee from the assembled XDR via extractFeeFromXdr
Returns { xdr, fee, simulationResult } — fee is in stroops

The TransactionModal converts stroops to XLM for display (e.g. 1000 stroops → 0.0001 XLM).

For read operations, client.call() is used directly (no fee needed).

Wallet Setup

On first visit, the app prompts the user to create or connect a smart wallet. The wallet is tied to the user’s device passkey (biometric or security key).

Create wallet — deploys a new smart wallet contract using NEXT_PUBLIC_WALLET_WASM_HASH
Connect wallet — reconnects an existing wallet by scanning for the passkey

The wallet contract ID is stored in localStorage and auto-reconnected on return visits.

Deploying Your Own WASM Hash

The testnet WASM hash b3eba29c256a2458faff84fc872226d29df37ad05a6a1c0efe2a95817d6765ec was built from the kalepail/passkey-kit next branch and is already deployed on testnet.

To deploy your own:


# Upload the wallet WASM
stellar contract upload \
  --wasm wallet.wasm \
  --source your-key \
  --network testnet

Set the returned hash in NEXT_PUBLIC_WALLET_WASM_HASH.

OZ Relayer Migration

This template uses passkey-kit v0.12.0 which replaced the deprecated Launchtube service with the OpenZeppelin Relayer.

Old (deprecated)	New
`LAUNCHTUBE_URL`	`NEXT_PUBLIC_RELAYER_URL`
`LAUNCHTUBE_JWT`	`NEXT_PUBLIC_RELAYER_API_KEY`
Launchtube endpoint	`https://channels.openzeppelin.com/testnet`

Stellar SDK Note

Vercel Deployment

The template includes vercel.json. Deploy with:


vercel deploy --prod

Set all NEXT_PUBLIC_* variables in Vercel dashboard → Settings → Environment Variables. The Next.js proxy (MCP_PROXY_TARGET) is server-side and must also be set.