frontier-os-app-builder 1.1.0 → 1.2.0

package/references/sdk/wallet.md

@@ -0,0 +1,334 @@
+# Wallet Module
+
+**Trigger keywords:** payment, pay, charge, pos, checkout, purchase, buy, sell, transfer, send money, balance, funds, money, wallet, fnd, swap, exchange, convert, token, deposit, on-ramp, fund, withdraw, off-ramp, bank, fiat, subscription, billing, price, cost, fee, tip, donate, donation
+
+Access via `sdk.getWallet()`. All methods use the current chain from the chain manager. Write operations require biometric authentication.
+
+---
+
+## Methods
+
+```typescript
+getBalance(): Promise<WalletBalance>
+```
+Returns raw balance breakdown (bigint values). To display, format each bigint field with `formatAmount()` from `@frontiertower/frontier-sdk`. Permission: `wallet:getBalance`
+
+```typescript
+getAddress(): Promise<string>
+```
+Returns the smart account contract address for the current chain. Permission: `wallet:getAddress`
+
+```typescript
+getSmartAccount(): Promise<SmartAccount>
+```
+Returns detailed smart account info including deployment status. Permission: `wallet:getSmartAccount`
+
+```typescript
+transferERC20(
+  tokenAddress: string,
+  to: string,
+  amount: bigint,
+  overrides?: GasOverrides
+): Promise<UserOperationReceipt>
+```
+Transfer ERC20 tokens. Amount in token's smallest unit. Permission: `wallet:transferERC20`
+
+```typescript
+approveERC20(
+  tokenAddress: string,
+  spender: string,
+  amount: bigint,
+  overrides?: GasOverrides
+): Promise<UserOperationReceipt>
+```
+Approve a spender for ERC20 tokens. Permission: `wallet:approveERC20`
+
+```typescript
+transferNative(
+  to: string,
+  amount: bigint,
+  overrides?: GasOverrides
+): Promise<UserOperationReceipt>
+```
+Transfer native currency (ETH). Amount in wei. Permission: `wallet:transferNative`
+
+```typescript
+executeCall(
+  call: ExecuteCall,
+  overrides?: GasOverrides
+): Promise<UserOperationReceipt>
+```
+Execute an arbitrary contract call. Permission: `wallet:executeCall`
+
+```typescript
+executeBatchCall(
+  calls: ExecuteCall[],
+  overrides?: GasOverrides
+): Promise<UserOperationReceipt>
+```
+Execute multiple calls atomically in a single transaction. Permission: `wallet:executeBatchCall`
+
+```typescript
+transferFrontierDollar(
+  to: string,
+  amount: bigint,
+  overrides?: GasOverrides
+): Promise<UserOperationReceipt>
+```
+Transfer FND (Frontier Network Dollar). Amount in base units — build with `parseAmount('10.5')` from `@frontiertower/frontier-sdk`. Permission: `wallet:transferFrontierDollar`
+
+```typescript
+transferInternalFrontierDollar(
+  to: string,
+  amount: bigint,
+  overrides?: GasOverrides
+): Promise<UserOperationReceipt>
+```
+Transfer iFND (Internal Frontier Network Dollar). Amount in base units — build with `parseAmount('10.5')` from `@frontiertower/frontier-sdk`. Permission: `wallet:transferInternalFrontierDollar`
+
+```typescript
+transferOverallFrontierDollar(
+  to: string,
+  amount: bigint,
+  overrides?: GasOverrides
+): Promise<UserOperationReceipt>
+```
+Transfer using iFND first, falling back to FND for the remainder. Permission: `wallet:transferOverallFrontierDollar`
+
+```typescript
+getSupportedTokens(): Promise<string[]>
+```
+Returns token symbols supported for swaps on the current chain (e.g. `['FND', 'USDC', 'WETH']`). Permission: `wallet:getSupportedTokens`
+
+```typescript
+swap(
+  sourceToken: string,
+  targetToken: string,
+  sourceNetwork: string,
+  targetNetwork: string,
+  amount: bigint
+): Promise<SwapResult>
+```
+Execute a token swap (same-chain or cross-chain). Amount in base units — build with `parseAmount('10.5')` from `@frontiertower/frontier-sdk`. Permission: `wallet:swap`
+
+```typescript
+quoteSwap(
+  sourceToken: string,
+  targetToken: string,
+  sourceNetwork: string,
+  targetNetwork: string,
+  amount: bigint
+): Promise<SwapQuote>
+```
+Get a swap quote without executing. Permission: `wallet:quoteSwap`
+
+```typescript
+getUsdDepositInstructions(): Promise<OnRampResponse<UsdDepositInstructions>>
+```
+Get US bank details for fiat-to-crypto on-ramp. Requires approved KYC. Permission: `wallet:getUsdDepositInstructions`
+
+```typescript
+getEurDepositInstructions(): Promise<OnRampResponse<EurDepositInstructions>>
+```
+Get SEPA bank details for EUR fiat-to-crypto on-ramp. Requires approved KYC. Permission: `wallet:getEurDepositInstructions`
+
+```typescript
+getLinkedBanks(): Promise<LinkedBanksResponse>
+```
+Get all linked bank accounts for off-ramp withdrawals. Requires approved KYC. Permission: `wallet:getLinkedBanks`
+
+```typescript
+linkUsBankAccount(
+  accountOwnerName: string,
+  bankName: string,
+  routingNumber: string,
+  accountNumber: string,
+  checkingOrSavings: 'checking' | 'savings',
+  address: BillingAddress
+): Promise<LinkBankResponse>
+```
+Link a US bank account for USD withdrawals via ACH. Requires approved KYC. Permission: `wallet:linkUsBankAccount`
+
+```typescript
+linkEuroAccount(
+  accountOwnerName: string,
+  accountOwnerType: AccountOwnerType,
+  firstName: string,
+  lastName: string,
+  ibanAccountNumber: string,
+  bic?: string
+): Promise<LinkBankResponse>
+```
+Link a EUR/IBAN bank account for SEPA withdrawals. Requires approved KYC. Permission: `wallet:linkEuroAccount`
+
+```typescript
+deleteLinkedBank(bankId: string): Promise<void>
+```
+Delete a linked bank account. Permission: `wallet:deleteLinkedBank`
+
+```typescript
+getDeprecatedSmartAccounts(): Promise<DeprecatedSmartAccount[]>
+```
+Get deprecated smart accounts that still have active gas sponsorship. Permission: `wallet:getDeprecatedSmartAccounts`
+
+---
+
+## Types
+
+```typescript
+interface SmartAccount {
+  id: number;
+  ownerAddress: string;
+  contractAddress: string | null;
+  network: string;
+  status: string;
+  deploymentTransactionHash: string;
+  createdAt: string;
+}
+
+interface WalletBalance {
+  total: bigint;
+  fnd: bigint;
+  internalFnd: bigint;
+}
+
+interface UserOperationReceipt {
+  userOpHash: string;
+  transactionHash: string;
+  blockNumber: bigint;
+  success: boolean;
+}
+
+interface GasOverrides {
+  maxFeePerGas?: bigint;
+  maxPriorityFeePerGas?: bigint;
+  gasLimit?: bigint;
+}
+
+interface ExecuteCall {
+  target: string;
+  value?: bigint;
+  data: string;
+}
+
+interface SwapParams {
+  sourceToken: string;
+  targetToken: string;
+  sourceNetwork: string;
+  targetNetwork: string;
+  amount: bigint;
+}
+
+enum SwapResultStatus {
+  COMPLETED = 'COMPLETED',
+  SUBMITTED = 'SUBMITTED',
+}
+
+interface SwapResult {
+  sourceChain: object;
+  targetChain: object;
+  sourceToken: object;
+  targetToken: object;
+  status: SwapResultStatus;
+}
+
+interface SwapQuote {
+  sourceChain: object;
+  targetChain: object;
+  sourceToken: object;
+  targetToken: object;
+  expectedAmountOut: bigint;
+  minAmountOut: bigint;
+}
+
+interface UsdDepositInstructions {
+  currency: 'usd';
+  bankName: string;
+  bankAddress: string;
+  bankRoutingNumber: string;
+  bankAccountNumber: string;
+  bankBeneficiaryName: string;
+  paymentRail: string;
+}
+
+interface EurDepositInstructions {
+  currency: 'eur';
+  iban: string;
+  bic: string;
+  accountHolderName: string;
+}
+
+interface OnRampResponse<T = UsdDepositInstructions | EurDepositInstructions> {
+  currency: 'usd' | 'eur';
+  depositInstructions: T;
+  destinationAddress: string;
+  destinationNetwork: string;
+}
+
+interface LinkedBank {
+  id: string;
+  bankName: string;
+  last4: string;
+  withdrawalAddress: string;
+  network: string;
+}
+
+interface LinkedBanksResponse {
+  banks: LinkedBank[];
+}
+
+interface LinkBankResponse {
+  externalAccountId: string;
+  bankName: string;
+  withdrawalAddress: string;
+  network: string;
+}
+
+interface BillingAddress {
+  streetLine1: string;
+  streetLine2?: string;
+  city: string;
+  state: string;
+  postalCode: string;
+  country: string;
+}
+
+type AccountOwnerType = 'individual' | 'business';
+
+interface DeprecatedSmartAccount {
+  id: number;
+  ownerAddress: string;
+  contractAddress: string;
+  network: string;
+  deprecatedAt: string;
+  version: number;
+}
+```
+
+---
+
+## Permissions (21)
+
+| Permission | Description |
+|---|---|
+| `wallet:getBalance` | Access wallet balance (raw bigint) |
+| `wallet:getAddress` | Access wallet address |
+| `wallet:getSmartAccount` | Access smart account details |
+| `wallet:transferERC20` | Transfer ERC20 tokens |
+| `wallet:approveERC20` | Approve ERC20 token spending |
+| `wallet:transferNative` | Transfer native currency (ETH) |
+| `wallet:transferFrontierDollar` | Transfer FND (Frontier Network Dollar) |
+| `wallet:transferInternalFrontierDollar` | Transfer iFND (Internal Frontier Network Dollar) |
+| `wallet:transferOverallFrontierDollar` | Transfer using iFND first, fallback to FND |
+| `wallet:executeCall` | Execute arbitrary contract call |
+| `wallet:executeBatchCall` | Execute multiple contract calls atomically |
+| `wallet:getSupportedTokens` | Get supported token symbols for swaps |
+| `wallet:swap` | Execute token swap (same-chain or cross-chain) |
+| `wallet:quoteSwap` | Get swap quote without executing |
+| `wallet:getUsdDepositInstructions` | Get USD bank deposit instructions (on-ramp) |
+| `wallet:getEurDepositInstructions` | Get EUR/SEPA deposit instructions (on-ramp) |
+| `wallet:getLinkedBanks` | Get linked bank accounts (off-ramp) |
+| `wallet:linkUsBankAccount` | Link US bank account for USD withdrawals |
+| `wallet:linkEuroAccount` | Link EUR/IBAN bank account for EUR withdrawals |
+| `wallet:deleteLinkedBank` | Delete a linked bank account |
+| `wallet:getDeprecatedSmartAccounts` | Get deprecated smart accounts with active gas sponsorship |

package/references/verification-rules.md

@@ -48,7 +48,7 @@ The `src/` directory must contain at minimum:
 src/
   main.tsx
   lib/
-    sdk-context.tsx
+    frontier-services.tsx
   views/
     Layout.tsx
   styles/
@@ -70,6 +70,8 @@ src/
     components/
 ```
 
+> **Note:** `src/lib/sdk-context.tsx` and `src/lib/sdk-services.tsx` exist only **after** the SDK Integration phase (Tier 2). They are not present during pre-integration phases, so S-02 (a Tier-1 check that runs after every phase) must not require them.
+
 **Pass condition:** All required paths exist. Optional paths should be present when the corresponding feature is used (e.g., `router.tsx` when `react-router-dom` is a dependency).
 
 ### S-03: No extraneous top-level files
@@ -130,24 +132,26 @@ if (standaloneHtml) {
 }
 ```
 
-### I-03: SdkProvider wrapping children in Layout.tsx
+### I-03: SdkProvider + FrontierServicesProvider wrapping children in Layout.tsx
 
-When inside the Frontier app, the Layout must wrap its children (either `<Outlet />` or a single component) with `<SdkProvider>`.
+When inside the Frontier app, the Layout must wrap its children with `<SdkProvider>` AND bridge the SDK into `<FrontierServicesProvider>`. Feature code consumes `useServices()`, so without `FrontierServicesProvider` the app **crashes at runtime** ("useServices must be used within FrontierServicesProvider").
 
-**Pass condition:** The return statement for the "in Frontier" case contains:
+**Pass condition:** Layout's "in Frontier" return path contains both providers:
 ```tsx
 <SdkProvider>
-  <Outlet />  {/* or a single component */}
+  <SdkServicesBridge>   {/* useSdk() → createSdkServices(sdk) → FrontierServicesProvider */}
+    <Outlet />
+  </SdkServicesBridge>
 </SdkProvider>
 ```
 
 ### I-04: useSdk() hook available and used
 
-`src/lib/sdk-context.tsx` must export `useSdk` and `SdkProvider`. Any view component that accesses the SDK must call `useSdk()`.
+`src/lib/sdk-context.tsx` must export `useSdk` and `SdkProvider`. Only `sdk-services.tsx` and `src/views/Layout.tsx` may consume them; feature code under `src/hooks/`, `src/views/`, and `src/components/` accesses the SDK indirectly through `useServices()` (see M-03), never `useSdk()` directly.
 
 **Pass condition:**
 - `sdk-context.tsx` exports `useSdk` and `SdkProvider`.
-- Every file that accesses SDK methods imports `useSdk` from `../lib/sdk-context` (or appropriate relative path) and calls it within the component body.
+- `useSdk()` / `SdkProvider` are consumed only by `sdk-services.tsx` and `Layout.tsx`; feature code uses `useServices()` from `../lib/frontier-services` (see M-03), not `useSdk`.
 - No direct `new FrontierSDK()` calls outside of `sdk-context.tsx`.
 
 ---
@@ -156,27 +160,23 @@ When inside the Frontier app, the Layout must wrap its children (either `<Outlet
 
 These verify configuration files have the correct content.
 
-### C-01: vercel.json has all 3 CORS origin blocks
+### C-01: vercel.json has CORS + CSP frame-ancestors for the 3 origins
 
 > **Tier 2 — SDK Integration phase only.**
 
-The `vercel.json` file must contain exactly 3 header blocks, one for each allowed origin:
-
-1. `https://os.frontiertower.io`
-2. `https://sandbox.os.frontiertower.io`
-3. `http://localhost:5173`
-
-Each block must include:
-- `Access-Control-Allow-Origin` matching the origin
+The `vercel.json` file uses a single unconditional header block containing:
+- `Access-Control-Allow-Origin: https://os.frontiertower.io` (the production origin)
 - `Access-Control-Allow-Methods: GET, OPTIONS`
 - `Access-Control-Allow-Headers: Content-Type`
+- `Content-Security-Policy` with `frame-ancestors` listing all 3 live origins (`https://os.frontiertower.io`, `https://sandbox.os.frontiertower.io`, `http://localhost:5173`) — this governs iframe embedding
+- security headers: `X-Content-Type-Options`, `Referrer-Policy`, `Permissions-Policy`
 
 It must also include the SPA rewrite:
 ```json
 { "source": "/(.*)", "destination": "/index.html" }
 ```
 
-**Pass condition:** All 3 origin blocks are present with correct headers. The rewrite rule exists.
+**Pass condition:** All 3 origins appear in the `frame-ancestors` directive, the CORS and security headers are present, and the rewrite rule exists.
 
 ### C-02: tsconfig.json has strict mode and vitest types
 
@@ -443,7 +443,7 @@ Source files under `src/hooks/`, `src/views/`, and `src/components/` must NOT im
 | I-02  | SDK           | createStandaloneHTML() fallback in Layout.tsx        | Tier 2 | Error    |
 | I-03  | SDK           | SdkProvider wrapping children in Layout.tsx          | Tier 2 | Error    |
 | I-04  | SDK           | useSdk() hook available and used                    | Tier 2 | Error    |
-| C-01  | Configuration | vercel.json has all 3 CORS origin blocks            | Tier 2 | Error    |
+| C-01  | Configuration | vercel.json: CORS + CSP frame-ancestors (3 origins) | Tier 2 | Error    |
 | C-02  | Configuration | tsconfig.json has strict mode and vitest types      | Tier 1 | Error    |
 | C-03  | Configuration | postcss.config.js imports @tailwindcss/postcss      | Tier 1 | Error    |
 | C-04  | Configuration | package.json has correct scripts                    | Tier 1 | Error    |

package/templates/app/frontier-services.tsx

@@ -1,5 +1,15 @@
 import { createContext, useContext, type ReactNode } from 'react';
 
+// ── Token amounts (bigint base units) ────────────────────────────────────────
+//
+// Since Frontier SDK v0.23, all FND amounts are bigint base units (FND_DECIMALS = 6).
+// WalletBalance fields and every transfer*/swap amount are bigint, NOT display strings.
+//   - Display a balance:  formatAmount(b.fnd)   → symbol-free decimal string (100_500000n → '100.5')
+//   - Parse user input:   parseAmount('10.5')   → bigint (throws InvalidAmountError on bad input)
+//   - Write:              wallet.transferFrontierDollar(to, parseAmount('10.5'))
+// Import formatAmount / parseAmount / FND_DECIMALS / InvalidAmountError from the package
+// ROOT '@frontiertower/frontier-sdk' (NOT the /ui-utils subpath). The SDK never adds '$'.
+
 // ── Shared Types ────────────────────────────────────────────────────────────
 
 export interface PaginatedResponse<T> {
@@ -15,12 +25,6 @@ export interface WalletBalance {
   internalFnd: bigint;
 }
 
-export interface WalletBalanceFormatted {
-  total: string;
-  fnd: string;
-  internalFnd: string;
-}
-
 export interface SmartAccount {
   id: number;
   ownerAddress: string;
@@ -63,8 +67,8 @@ export interface SwapQuote {
   targetChain: object;
   sourceToken: object;
   targetToken: object;
-  expectedAmountOut: string;
-  minAmountOut: string;
+  expectedAmountOut: bigint;
+  minAmountOut: bigint;
 }
 
 export interface OnRampResponse<T> {
@@ -407,6 +411,57 @@ export interface FrontierEvent {
   color: string;
   reviewStatus: string;
   status: string;
+  isHost?: boolean;
+  deposit?: EventDeposit | null;
+}
+
+// ── Events Deposit Types ──────────────────────────────────────────────────────
+
+export type DepositStatus =
+  | 'not_required'
+  | 'required'
+  | 'pending'
+  | 'secured'
+  | 'released'
+  | 'withheld'
+  | 'failed';
+
+export type CryptoDepositStatus =
+  | 'secured'
+  | 'awaiting_payment'
+  | 'grant'
+  | 'released'
+  | 'withheld'
+  | 'failed';
+
+export interface EventDeposit {
+  status: DepositStatus;
+  amount: number;
+  currency: string;
+}
+
+export interface DepositPreflightToken {
+  key: string;
+  address: string;
+  decimals: number;
+  baseUnits: string;
+}
+
+export interface DepositPreflight {
+  spender: string;
+  network: string;
+  amount: string;
+  currency: string;
+  tokens: DepositPreflightToken[];
+}
+
+export interface DepositResult {
+  provider: 'crypto';
+  status: CryptoDepositStatus;
+  amount: string;
+  currency: string;
+  reference: string;
+  statusReason: string;
 }
 
 export interface EventLocation {
@@ -481,7 +536,6 @@ export interface DeepLinkData {
 
 export interface WalletService {
   getBalance(): Promise<WalletBalance>;
-  getBalanceFormatted(): Promise<WalletBalanceFormatted>;
   getAddress(): Promise<string>;
   getSmartAccount(): Promise<SmartAccount>;
   transferERC20(tokenAddress: string, to: string, amount: bigint, overrides?: GasOverrides): Promise<UserOperationReceipt>;
@@ -489,12 +543,12 @@ export interface WalletService {
   transferNative(to: string, amount: bigint, overrides?: GasOverrides): Promise<UserOperationReceipt>;
   executeCall(call: ExecuteCall, overrides?: GasOverrides): Promise<UserOperationReceipt>;
   executeBatchCall(calls: ExecuteCall[], overrides?: GasOverrides): Promise<UserOperationReceipt>;
-  transferFrontierDollar(to: string, amount: string, overrides?: GasOverrides): Promise<UserOperationReceipt>;
-  transferInternalFrontierDollar(to: string, amount: string, overrides?: GasOverrides): Promise<UserOperationReceipt>;
-  transferOverallFrontierDollar(to: string, amount: string, overrides?: GasOverrides): Promise<UserOperationReceipt>;
+  transferFrontierDollar(to: string, amount: bigint, overrides?: GasOverrides): Promise<UserOperationReceipt>;
+  transferInternalFrontierDollar(to: string, amount: bigint, overrides?: GasOverrides): Promise<UserOperationReceipt>;
+  transferOverallFrontierDollar(to: string, amount: bigint, overrides?: GasOverrides): Promise<UserOperationReceipt>;
   getSupportedTokens(): Promise<string[]>;
-  swap(sourceToken: string, targetToken: string, sourceNetwork: string, targetNetwork: string, amount: string): Promise<SwapResult>;
-  quoteSwap(sourceToken: string, targetToken: string, sourceNetwork: string, targetNetwork: string, amount: string): Promise<SwapQuote>;
+  swap(sourceToken: string, targetToken: string, sourceNetwork: string, targetNetwork: string, amount: bigint): Promise<SwapResult>;
+  quoteSwap(sourceToken: string, targetToken: string, sourceNetwork: string, targetNetwork: string, amount: bigint): Promise<SwapQuote>;
   getUsdDepositInstructions(): Promise<OnRampResponse<UsdDepositInstructions>>;
   getEurDepositInstructions(): Promise<OnRampResponse<EurDepositInstructions>>;
   getLinkedBanks(): Promise<LinkedBanksResponse>;
@@ -505,7 +559,7 @@ export interface WalletService {
 }
 
 export interface StorageService {
-  get<T = any>(key: string): Promise<T>;
+  get<T = any>(key: string): Promise<T | null>;
   set(key: string, value: any): Promise<void>;
   remove(key: string): Promise<void>;
   clear(): Promise<void>;
@@ -579,6 +633,8 @@ export interface EventsService {
   listLocations(payload?: { locationType?: LocationType }): Promise<EventLocation[]>;
   listRoomBookings(payload?: { locationId?: string; date?: string; startDate?: string; endDate?: string; page?: number }): Promise<PaginatedResponse<RoomBooking>>;
   createRoomBooking(payload: { startsAt: string; endsAt: string; location: string }): Promise<RoomBooking>;
+  getCryptoDepositPreflight(payload: { eventId: number }): Promise<DepositPreflight>;
+  placeCryptoDeposit(payload: { eventId: number }): Promise<DepositResult>;
 }
 
 export interface OfficesService {
@@ -639,7 +695,6 @@ async function mockWriteOp(module: string, method: string): Promise<UserOperatio
 export function createMockServices(): FrontierServices {
   const wallet: WalletService = {
     async getBalance() { mockLog('wallet', 'getBalance'); return { total: BigInt(10_500000), fnd: BigInt(7_500000), internalFnd: BigInt(3_000000) }; },
-    async getBalanceFormatted() { mockLog('wallet', 'getBalanceFormatted'); return { total: '$100.00', fnd: '$75.00', internalFnd: '$25.00' }; },
     async getAddress() { mockLog('wallet', 'getAddress'); return '0x1234567890abcdef1234567890abcdef12345678'; },
     async getSmartAccount() { mockLog('wallet', 'getSmartAccount'); return { id: 1, ownerAddress: '0xowner', contractAddress: '0xcontract', network: 'base-sepolia', status: 'deployed', deploymentTransactionHash: '0xdeploy', createdAt: new Date().toISOString() }; },
     async transferERC20() { return mockWriteOp('wallet', 'transferERC20'); },
@@ -652,7 +707,7 @@ export function createMockServices(): FrontierServices {
     async transferOverallFrontierDollar() { return mockWriteOp('wallet', 'transferOverallFrontierDollar'); },
     async getSupportedTokens() { mockLog('wallet', 'getSupportedTokens'); return ['FND', 'USDC', 'WETH']; },
     async swap() { mockLog('wallet', 'swap'); await delay(1000); return { sourceChain: {}, targetChain: {}, sourceToken: {}, targetToken: {}, status: 'COMPLETED' as const }; },
-    async quoteSwap() { mockLog('wallet', 'quoteSwap'); return { sourceChain: {}, targetChain: {}, sourceToken: {}, targetToken: {}, expectedAmountOut: '10.00', minAmountOut: '9.95' }; },
+    async quoteSwap() { mockLog('wallet', 'quoteSwap'); return { sourceChain: {}, targetChain: {}, sourceToken: {}, targetToken: {}, expectedAmountOut: BigInt(10_000000), minAmountOut: BigInt(9_950000) }; },
     async getUsdDepositInstructions() { mockLog('wallet', 'getUsdDepositInstructions'); return { currency: 'usd', depositInstructions: { currency: 'usd', bankName: 'Mock Bank', bankAddress: '123 Mock St', bankRoutingNumber: '000000000', bankAccountNumber: '1234567890', bankBeneficiaryName: 'Frontier Mock', paymentRail: 'ach' }, destinationAddress: '0xdest', destinationNetwork: 'base' }; },
     async getEurDepositInstructions() { mockLog('wallet', 'getEurDepositInstructions'); return { currency: 'eur', depositInstructions: { currency: 'eur', iban: 'DE00000000000000000000', bic: 'MOCKDEFF', accountHolderName: 'Frontier Mock' }, destinationAddress: '0xdest', destinationNetwork: 'base' }; },
     async getLinkedBanks() { mockLog('wallet', 'getLinkedBanks'); return { banks: [] }; },
@@ -663,7 +718,7 @@ export function createMockServices(): FrontierServices {
   };
 
   const storage: StorageService = {
-    async get<T = any>(key: string): Promise<T> {
+    async get<T = any>(key: string): Promise<T | null> {
       mockLog('storage', 'get');
       const raw = localStorage.getItem(MOCK_PREFIX + key);
       return raw ? JSON.parse(raw) : null;
@@ -765,6 +820,8 @@ export function createMockServices(): FrontierServices {
     async listLocations() { mockLog('events', 'listLocations'); return []; },
     async listRoomBookings() { mockLog('events', 'listRoomBookings'); return emptyPage(); },
     async createRoomBooking() { mockLog('events', 'createRoomBooking'); await delay(1000); return { id: 1, startsAt: new Date().toISOString(), endsAt: new Date(Date.now() + 3600000).toISOString(), location: 'mock-room' }; },
+    async getCryptoDepositPreflight() { mockLog('events', 'getCryptoDepositPreflight'); return { spender: '0xspender', network: 'base-sepolia', amount: '400.00', currency: 'usd', tokens: [{ key: 'ifnd_token', address: '0xifnd', decimals: 6, baseUnits: '400000000' }, { key: 'fnd_token', address: '0xfnd', decimals: 6, baseUnits: '400000000' }] }; },
+    async placeCryptoDeposit() { mockLog('events', 'placeCryptoDeposit'); await delay(1000); return { provider: 'crypto', status: 'secured', amount: '400.00', currency: 'usd', reference: '0xmocktxhash', statusReason: '' }; },
   };
 
   const offices: OfficesService = {

package/templates/app/layout.tsx

@@ -1,21 +1,27 @@
-import { useEffect, useState } from 'react';
+import { useEffect, useMemo, useState, type ReactNode } from 'react';
 import { Outlet } from 'react-router-dom';
 import { isInFrontierApp, createStandaloneHTML } from '@frontiertower/frontier-sdk/ui-utils';
-import { SdkProvider } from '../lib/sdk-context';
+import { SdkProvider, useSdk } from '../lib/sdk-context';
+import { FrontierServicesProvider } from '../lib/frontier-services';
+import { createSdkServices } from '../lib/sdk-services';
+
+// Bridges the live SDK (from SdkProvider) into the FrontierServices seam that
+// feature code consumes via useServices(). Keeps feature code SDK-agnostic: the
+// exact same components run against mocks (standalone) and the real SDK (iframe).
+const SdkServicesBridge = ({ children }: { children: ReactNode }) => {
+  const sdk = useSdk();
+  const services = useMemo(() => createSdkServices(sdk), [sdk]);
+  return <FrontierServicesProvider services={services}>{children}</FrontierServicesProvider>;
+};
 
 export const Layout = () => {
   const [loading, setLoading] = useState(true);
   const [standaloneHtml, setStandaloneHtml] = useState('');
 
   useEffect(() => {
-    const inFrontier = isInFrontierApp();
-
-    if (!inFrontier) {
+    if (!isInFrontierApp()) {
       setStandaloneHtml(createStandaloneHTML('{{APP_NAME}}'));
-      setLoading(false);
-      return;
     }
-
     setLoading(false);
   }, []);
 
@@ -37,9 +43,13 @@ export const Layout = () => {
     );
   }
 
+  // In-frame: provide both the raw SDK (useSdk) and the SDK-backed services
+  // seam (useServices) so every feature component works unchanged from standalone.
   return (
     <SdkProvider>
-      <Outlet />
+      <SdkServicesBridge>
+        <Outlet />
+      </SdkServicesBridge>
     </SdkProvider>
   );
 };

package/templates/app/package.json

@@ -15,7 +15,8 @@
     "react": "^19.2.3",
     "react-dom": "^19.2.3",
     "react-icons": "^5.5.0",
-    "react-router-dom": "^7.12.0"
+    "react-router-dom": "^7.12.0",
+    "viem": "^2.44.0"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4.1.18",

package/templates/app/public/favicon.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" width="32" height="32" role="img" aria-label="Frontier">
+  <circle cx="16" cy="16" r="14" fill="#764AE2" />
+</svg>