@orbi-wallet/sdk 0.0.1

package/dist/client.d.ts

@@ -0,0 +1,99 @@
+/**
+ * @orbi/sdk — Orbi Smart Wallet SDK
+ *
+ * Lets any Stellar dApp integrate Orbi passkey wallets using a redirect flow.
+ * Works on all devices and browsers — no popups, no extensions needed.
+ *
+ * Quick start (user pays gas):
+ *   const orbi = new OrbiClient({ apiUrl: 'https://api.orbiwallet.xyz' });
+ *
+ * Quick start (dApp sponsors gas):
+ *   const orbi = new OrbiClient({
+ *     apiUrl: 'https://api.orbiwallet.xyz',
+ *     apiKey: 'YOUR_API_KEY',  // <-- enables gasless
+ *   });
+ *
+ * Flow:
+ *   1. orbi.connect({ redirectUrl })          — redirect user to connect wallet
+ *   2. orbi.handleCallback()                  — on return, exchange token for wallet data
+ *   3. orbi.sign({ ..., redirectUrl })        — redirect user to approve transaction
+ *   4. orbi.handleSignCallback() → bundle()   — on return, submit signed tx
+ *   5. orbi.waitForConfirmation(opId)         — wait for on-chain confirmation
+ */
+import type { OrbiClientConfig, OpStatus, DeployerBalance } from './types';
+export declare class OrbiClient {
+    private apiUrl;
+    private apiKey?;
+    constructor(config: OrbiClientConfig);
+    private authHeaders;
+    /** Redirect the user to Orbi to connect their wallet. */
+    connect(params: {
+        redirectUrl: string;
+    }): void;
+    /** Call this on your callback page after orbi.connect() redirects back. */
+    handleCallback(): Promise<{
+        walletAddress: string;
+        passkeyId: string;
+        email: string;
+    } | null>;
+    /**
+     * Redirect the user to Orbi to approve a transaction with their passkey.
+     * If apiKey is set, the user will see the fee as sponsored — they pay nothing.
+     */
+    sign(params: {
+        walletAddress: string;
+        contractId: string;
+        functionName: string;
+        argsXdr: string[];
+        redirectUrl: string;
+    }): void;
+    /** Call this on your sign-callback page after orbi.sign() redirects back. */
+    handleSignCallback(): {
+        signedAuthEntryXdr: string;
+        quoteId: string;
+        argsXdr: string[];
+        nativeSacId: string;
+        walletAddress: string;
+    } | null;
+    /** Redirect the user to add a token to their Orbi wallet. */
+    watchAsset(params: {
+        contractId: string;
+        redirectUrl: string;
+    }): void;
+    /** Call this on your callback page after orbi.watchAsset() redirects back. */
+    handleWatchAssetCallback(): {
+        contractId: string;
+        added: boolean;
+    } | null;
+    /**
+     * Submit a signed operation to the Orbi relay.
+     * If apiKey is set and a deployer is configured, gas is sponsored automatically.
+     */
+    bundle(params: {
+        walletAddress: string;
+        quoteId: string;
+        signedAuthEntryXdr: string;
+        contractId: string;
+        functionName: string;
+        argsXdr: string[];
+    }): Promise<{
+        opId: string;
+    }>;
+    /** One-shot status check for an operation. */
+    getStatus(opId: string): Promise<OpStatus>;
+    /** Wait for confirmed or failed via SSE (~5s on Stellar). */
+    waitForConfirmation(opId: string): Promise<OpStatus>;
+    /** Register a new developer account. Returns a one-time API key — save it. */
+    register(params: {
+        developerName: string;
+        email: string;
+        deployerPublicKey?: string;
+    }): Promise<{
+        apiKey: string;
+        message: string;
+    }>;
+    /** Set or update the deployer (gas tank) address for this API key. */
+    setDeployer(deployerPublicKey: string): Promise<void>;
+    /** Check the XLM balance of your gas tank. */
+    getDeployerBalance(): Promise<DeployerBalance>;
+}

package/dist/client.js

@@ -0,0 +1,213 @@
+"use strict";
+/**
+ * @orbi/sdk — Orbi Smart Wallet SDK
+ *
+ * Lets any Stellar dApp integrate Orbi passkey wallets using a redirect flow.
+ * Works on all devices and browsers — no popups, no extensions needed.
+ *
+ * Quick start (user pays gas):
+ *   const orbi = new OrbiClient({ apiUrl: 'https://api.orbiwallet.xyz' });
+ *
+ * Quick start (dApp sponsors gas):
+ *   const orbi = new OrbiClient({
+ *     apiUrl: 'https://api.orbiwallet.xyz',
+ *     apiKey: 'YOUR_API_KEY',  // <-- enables gasless
+ *   });
+ *
+ * Flow:
+ *   1. orbi.connect({ redirectUrl })          — redirect user to connect wallet
+ *   2. orbi.handleCallback()                  — on return, exchange token for wallet data
+ *   3. orbi.sign({ ..., redirectUrl })        — redirect user to approve transaction
+ *   4. orbi.handleSignCallback() → bundle()   — on return, submit signed tx
+ *   5. orbi.waitForConfirmation(opId)         — wait for on-chain confirmation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OrbiClient = void 0;
+const KEYS_URL = 'https://keys.orbiwallet.xyz';
+class OrbiClient {
+    constructor(config) {
+        this.apiUrl = config.apiUrl.replace(/\/$/, '');
+        this.apiKey = config.apiKey;
+    }
+    authHeaders() {
+        return this.apiKey ? { Authorization: `Bearer ${this.apiKey}` } : {};
+    }
+    // ── Wallet connection ───────────────────────────────────────────────────────
+    /** Redirect the user to Orbi to connect their wallet. */
+    connect(params) {
+        const url = new URL(`${KEYS_URL}/connect`);
+        url.searchParams.set('redirect', params.redirectUrl);
+        url.searchParams.set('origin', window.location.origin);
+        window.location.href = url.toString();
+    }
+    /** Call this on your callback page after orbi.connect() redirects back. */
+    async handleCallback() {
+        const params = new URLSearchParams(window.location.search);
+        const token = params.get('token');
+        if (!token)
+            return null;
+        const res = await fetch(`${this.apiUrl}/v1/auth/tokens/${token}`);
+        if (!res.ok)
+            throw new Error('Invalid or expired Orbi token');
+        return res.json();
+    }
+    // ── Transaction signing ─────────────────────────────────────────────────────
+    /**
+     * Redirect the user to Orbi to approve a transaction with their passkey.
+     * If apiKey is set, the user will see the fee as sponsored — they pay nothing.
+     */
+    sign(params) {
+        const url = new URL(`${KEYS_URL}/sign`);
+        url.searchParams.set('redirect', params.redirectUrl);
+        url.searchParams.set('origin', window.location.origin);
+        url.searchParams.set('walletAddress', params.walletAddress);
+        url.searchParams.set('contractId', params.contractId);
+        url.searchParams.set('functionName', params.functionName);
+        url.searchParams.set('argsXdr', JSON.stringify(params.argsXdr));
+        if (this.apiKey)
+            url.searchParams.set('apiKey', this.apiKey);
+        window.location.href = url.toString();
+    }
+    /** Call this on your sign-callback page after orbi.sign() redirects back. */
+    handleSignCallback() {
+        const params = new URLSearchParams(window.location.search);
+        const signedXdr = params.get('signedXdr');
+        const quoteId = params.get('quoteId');
+        const argsXdrRaw = params.get('argsXdr');
+        const nativeSacId = params.get('nativeSacId');
+        const walletAddress = params.get('walletAddress');
+        if (!signedXdr || !quoteId || !argsXdrRaw || !nativeSacId || !walletAddress)
+            return null;
+        return {
+            signedAuthEntryXdr: signedXdr,
+            quoteId,
+            argsXdr: JSON.parse(argsXdrRaw),
+            nativeSacId,
+            walletAddress,
+        };
+    }
+    // ── Token management ────────────────────────────────────────────────────────
+    /** Redirect the user to add a token to their Orbi wallet. */
+    watchAsset(params) {
+        const url = new URL(`${KEYS_URL}/watch-asset`);
+        url.searchParams.set('contractId', params.contractId);
+        url.searchParams.set('redirect', params.redirectUrl);
+        url.searchParams.set('origin', window.location.origin);
+        window.location.href = url.toString();
+    }
+    /** Call this on your callback page after orbi.watchAsset() redirects back. */
+    handleWatchAssetCallback() {
+        const params = new URLSearchParams(window.location.search);
+        const contractId = params.get('watchedContractId');
+        if (!contractId)
+            return null;
+        return { contractId, added: params.get('watched') === 'true' };
+    }
+    // ── Relay API ───────────────────────────────────────────────────────────────
+    /**
+     * Submit a signed operation to the Orbi relay.
+     * If apiKey is set and a deployer is configured, gas is sponsored automatically.
+     */
+    async bundle(params) {
+        const res = await fetch(`${this.apiUrl}/v1/bundle`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                ...this.authHeaders(),
+            },
+            body: JSON.stringify({
+                walletAddress: params.walletAddress,
+                quoteId: params.quoteId,
+                authEntryXdr: params.signedAuthEntryXdr,
+                call: {
+                    contractId: params.contractId,
+                    function: params.functionName,
+                    argsXdr: params.argsXdr,
+                },
+            }),
+        });
+        if (!res.ok) {
+            const err = await res.json().catch(() => ({}));
+            throw new Error(err.error ?? `Bundle failed: ${res.status}`);
+        }
+        return res.json();
+    }
+    /** One-shot status check for an operation. */
+    async getStatus(opId) {
+        const res = await fetch(`${this.apiUrl}/v1/status/${opId}`);
+        if (!res.ok)
+            throw new Error(`Status check failed: ${res.status}`);
+        return res.json();
+    }
+    /** Wait for confirmed or failed via SSE (~5s on Stellar). */
+    waitForConfirmation(opId) {
+        return new Promise((resolve, reject) => {
+            const es = new EventSource(`${this.apiUrl}/v1/wallet/events/${opId}`);
+            es.onmessage = (e) => {
+                try {
+                    const data = JSON.parse(e.data);
+                    es.close();
+                    if (data.status === 'confirmed') {
+                        resolve({ opId, status: 'confirmed', txHash: data.txHash ?? null, error: null });
+                    }
+                    else if (data.status === 'failed') {
+                        resolve({ opId, status: 'failed', txHash: null, error: data.error ?? 'Transaction failed' });
+                    }
+                    else if (data.status === 'timeout') {
+                        reject(new Error(`Op ${opId} timed out`));
+                    }
+                }
+                catch {
+                    es.close();
+                    reject(new Error('Invalid SSE response'));
+                }
+            };
+            es.onerror = () => {
+                es.close();
+                reject(new Error(`Lost connection waiting for op ${opId}`));
+            };
+        });
+    }
+    // ── Gas sponsorship onboarding ──────────────────────────────────────────────
+    /** Register a new developer account. Returns a one-time API key — save it. */
+    async register(params) {
+        const res = await fetch(`${this.apiUrl}/v1/account/register`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(params),
+        });
+        if (!res.ok) {
+            const err = await res.json().catch(() => ({}));
+            throw new Error(err.error ?? `Registration failed: ${res.status}`);
+        }
+        return res.json();
+    }
+    /** Set or update the deployer (gas tank) address for this API key. */
+    async setDeployer(deployerPublicKey) {
+        if (!this.apiKey)
+            throw new Error('apiKey required — pass it in the OrbiClient constructor');
+        const res = await fetch(`${this.apiUrl}/v1/account/deployer`, {
+            method: 'PATCH',
+            headers: { 'Content-Type': 'application/json', ...this.authHeaders() },
+            body: JSON.stringify({ deployerPublicKey }),
+        });
+        if (!res.ok) {
+            const err = await res.json().catch(() => ({}));
+            throw new Error(err.error ?? `Set deployer failed: ${res.status}`);
+        }
+    }
+    /** Check the XLM balance of your gas tank. */
+    async getDeployerBalance() {
+        if (!this.apiKey)
+            throw new Error('apiKey required — pass it in the OrbiClient constructor');
+        const res = await fetch(`${this.apiUrl}/v1/account/balance`, {
+            headers: this.authHeaders(),
+        });
+        if (!res.ok) {
+            const err = await res.json().catch(() => ({}));
+            throw new Error(err.error ?? `Balance fetch failed: ${res.status}`);
+        }
+        return res.json();
+    }
+}
+exports.OrbiClient = OrbiClient;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { OrbiClient } from './client';
+export { deriveWalletAddress } from './wallet';
+export type { OrbiClientConfig, QuoteResult, BundleResult, OpStatus, OrbiNetwork, DeployerBalance } from './types';

package/dist/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveWalletAddress = exports.OrbiClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "OrbiClient", { enumerable: true, get: function () { return client_1.OrbiClient; } });
+var wallet_1 = require("./wallet");
+Object.defineProperty(exports, "deriveWalletAddress", { enumerable: true, get: function () { return wallet_1.deriveWalletAddress; } });

package/dist/types.d.ts

@@ -0,0 +1,32 @@
+export type OrbiNetwork = 'testnet' | 'mainnet';
+export interface OrbiClientConfig {
+    /** Orbi relay API URL — https://api.orbiwallet.xyz */
+    apiUrl: string;
+    /** Optional: your API key if required by the relay */
+    apiKey?: string;
+    network?: OrbiNetwork;
+}
+export interface QuoteResult {
+    quoteId: string;
+    feeStroops: number;
+    feeXlm: string;
+    expiresAtLedger: number;
+    currentLedger: number;
+    nativeSacId: string;
+    feeCollectorAddress: string;
+    authEntryXdr: string;
+}
+export interface BundleResult {
+    opId: string;
+}
+export interface OpStatus {
+    opId: string;
+    status: 'pending' | 'batched' | 'confirmed' | 'failed';
+    txHash: string | null;
+    error: string | null;
+}
+export interface DeployerBalance {
+    address: string;
+    balanceXlm: string;
+    balanceStroops: string;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/wallet.d.ts

@@ -0,0 +1,16 @@
+export type OrbiNetwork = 'testnet' | 'mainnet';
+/**
+ * Derive the deterministic wallet C-address for a passkey ID.
+ *
+ * Matches the relay's deriveWalletAddress — same formula:
+ *   salt    = sha256(passkey_id)
+ *   address = sha256(networkId + deployer_G_address + salt)
+ *
+ * Call this immediately after passkey creation to show the user their
+ * address — no transaction or network call needed.
+ */
+export declare function deriveWalletAddress(params: {
+    passkeyId: Uint8Array;
+    deployerPublicKey: string;
+    network?: OrbiNetwork;
+}): string;

package/dist/wallet.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveWalletAddress = deriveWalletAddress;
+const stellar_sdk_1 = require("@stellar/stellar-sdk");
+const PASSPHRASES = {
+    testnet: stellar_sdk_1.Networks.TESTNET,
+    mainnet: stellar_sdk_1.Networks.PUBLIC,
+};
+/**
+ * Derive the deterministic wallet C-address for a passkey ID.
+ *
+ * Matches the relay's deriveWalletAddress — same formula:
+ *   salt    = sha256(passkey_id)
+ *   address = sha256(networkId + deployer_G_address + salt)
+ *
+ * Call this immediately after passkey creation to show the user their
+ * address — no transaction or network call needed.
+ */
+function deriveWalletAddress(params) {
+    const { passkeyId, deployerPublicKey, network = 'testnet' } = params;
+    const networkPassphrase = PASSPHRASES[network];
+    const salt = (0, stellar_sdk_1.hash)(Buffer.from(passkeyId));
+    const networkId = (0, stellar_sdk_1.hash)(Buffer.from(networkPassphrase));
+    const preimage = stellar_sdk_1.xdr.HashIdPreimage.envelopeTypeContractId(new stellar_sdk_1.xdr.HashIdPreimageContractId({
+        networkId: Buffer.from(networkId),
+        contractIdPreimage: stellar_sdk_1.xdr.ContractIdPreimage.contractIdPreimageFromAddress(new stellar_sdk_1.xdr.ContractIdPreimageFromAddress({
+            address: new stellar_sdk_1.Address(deployerPublicKey).toScAddress(),
+            salt: Buffer.from(salt),
+        })),
+    }));
+    const contractId = (0, stellar_sdk_1.hash)(preimage.toXDR());
+    return stellar_sdk_1.StrKey.encodeContract(contractId);
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@orbi-wallet/sdk",
+  "version": "0.0.1",
+  "description": "Orbi Smart Wallet SDK — connect any dApp to Orbi passkey wallets with optional gasless transactions",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist"],
+  "license": "MIT",
+  "keywords": ["stellar", "smart-wallet", "passkey", "gasless", "soroban", "sdk"],
+  "homepage": "https://orbiwallet.xyz",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Novablitz404/orbi-smart-wallet"
+  },
+  "bugs": {
+    "url": "https://github.com/Novablitz404/orbi-smart-wallet/issues"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "dependencies": {
+    "@stellar/stellar-sdk": "^15.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.2",
+    "typescript": "^5.5.2"
+  },
+  "peerDependencies": {
+    "@stellar/stellar-sdk": "^15.1.0"
+  }
+}