Skip to main content

​
Overview

Use starkzap-native when integrating StarkZap in React Native/Expo apps. It re-exports the SDK API and adds a Metro helper (starkzap-native/metro) for runtime polyfills and resolver compatibility.

​
1) Install Packages

Install the React Native package and required runtime peers: 
npm install starkzap-native
npm install react-native-get-random-values fast-text-encoding buffer @ethersproject/shims
Optional dependencies by feature: 
# Ethereum bridge routes
npm install ethers

# Solana bridge routes
npm install @solana/web3.js @hyperlane-xyz/sdk @hyperlane-xyz/registry @hyperlane-xyz/utils

​
2) Configure Metro

Set up Metro once and wrap your config with withStarkzap: 
// metro.config.js
const { getDefaultConfig } = require("expo/metro-config");
const { withStarkzap } = require("starkzap-native/metro");

const config = getDefaultConfig(__dirname);

// Optional: add your own resolver overrides before wrapping.
module.exports = withStarkzap(config);
withStarkzap injects required polyfills and resolver handling for StarkZap dependencies.

​
3) Initialize the SDK

Import from starkzap-native and use the same onboarding APIs as web: 
import { StarkZap, OnboardStrategy, StarkSigner } from "starkzap-native";

const sdk = new StarkZap({ network: "sepolia" });

const { wallet } = await sdk.onboard({
  strategy: OnboardStrategy.Signer,
  account: { signer: new StarkSigner("0xYOUR_PRIVATE_KEY") },
  deploy: "if_needed",
});
For Privy-based onboarding, see Privy Integration.

​
4) Cartridge (native session)

When your starkzap-native version supports it, you can onboard with Cartridge using an in-app browser / deep-link session flow (not the web @cartridge/controller popup).
  1. Register the native Cartridge adapter once at app startup, before connectCartridge() or onboard({ strategy: OnboardStrategy.Cartridge }). Exact export names depend on your SDK version (for example registerCartridgeTsAdapter / registerCartridgeNativeAdapter).
  2. Pass policies and/or a Cartridge preset that resolves policies for your chain (same concepts as Cartridge Controller).
  3. Align rpcUrl / chainId (or network) on new StarkZap({ ... }) with the session and paymaster you target.
  4. Deploy: native Cartridge flows often default to deploy: "never" or recommend it when deployment semantics differ from the browser Controller. Pass deploy: "if_needed" explicitly if you need core-style deployment checks.
  5. Fees: sponsored execution on native is tied to the session wallet (commonly feeMode: "sponsored" only for matching policy paths).
See Cartridge Controller for policy and paymaster behavior, and the examples/tic-tac-toe app in the Starkzap repository when available for a full Expo reference.

​
5) External Wallet Providers (Optional)

If your app uses WalletConnect/Reown for external wallets, initialize its RN compatibility layer at app startup: 
import "@walletconnect/react-native-compat";
Then pass the resulting providers into StarkZap external wallet adapters as described in Bridging.
If connectCartridge or Cartridge onboarding throws not implemented, your installed starkzap-native build does not ship the native adapter yet — upgrade to a version that documents native Cartridge, or use Signer / Privy until then.

​
Next Steps