@iamgame/wallet-sdk-server 0.1.0

package/README.md

@@ -0,0 +1,28 @@
+# @iamgame/wallet-sdk-server
+
+Backend SDK for [IAMGame Wallet](https://wallet.iamgame.com). Authenticated with your **secret
+key** (`sk_`) — server-to-server only. Two jobs: **verify wallet sessions** at login, and run the
+**high-frequency money ledger**. The browser must never hold an `sk_` or call `win` on itself.
+
+All amounts are `bigint` integer base units (lamports / micro-USDC).
+
+```ts
+import { IAMGameWalletServer } from "@iamgame/wallet-sdk-server";
+
+const wallet = new IAMGameWalletServer({
+  secretKey: process.env.IAMGAME_WALLET_SECRET_KEY!, // sk_live_... / sk_test_...
+  baseUrl: "https://api-wallet.iamgame.com/v1",
+});
+
+// Login: verify the player's session token, then mint your own app JWT.
+const verified = await wallet.verifySession(sessionToken);
+// → { userId, walletAddress, wallets, identities, environment }
+
+// Ledger: lock once, run the hot path, settle the net.
+const s = await wallet.ledger.openSession({ userId, gameCode: "momentum", currency: "USDC", lockAmount: 50_000_000n });
+await wallet.ledger.bet({ sessionToken: s.sessionToken, transactionUuid: "r1-bet", amount: 1_000_000n, round: "r1" });
+await wallet.ledger.win({ sessionToken: s.sessionToken, transactionUuid: "r1-win", referenceTransactionUuid: "r1-bet", amount: 1_800_000n, round: "r1", roundClosed: true });
+const { payout } = await wallet.ledger.settleSession(s.sessionToken);
+```
+
+See the full guide at https://wallet.iamgame.com/docs.

package/dist/index.cjs

@@ -0,0 +1,151 @@
+'use strict';
+
+// ../../solven/sdk-server/src/errors.ts
+var SolvenServerError = class _SolvenServerError extends Error {
+  constructor(args) {
+    super(args.message);
+    this.name = "SolvenServerError";
+    this.code = args.code;
+    this.httpStatus = args.httpStatus;
+    this.details = args.details;
+  }
+  static fromEnvelope(httpStatus, env) {
+    return new _SolvenServerError({
+      code: env.code,
+      message: env.message,
+      httpStatus,
+      details: env.details
+    });
+  }
+};
+
+// ../../solven/sdk-server/src/client.ts
+var LedgerApi = class {
+  constructor(call) {
+    this.call = call;
+  }
+  async openSession(args) {
+    const r = await this.call("/ledger/sessions", {
+      userId: args.userId,
+      gameCode: args.gameCode,
+      currency: args.currency,
+      lockAmount: args.lockAmount.toString()
+    });
+    return {
+      sessionToken: r.sessionToken,
+      sessionId: r.sessionId,
+      currency: r.currency,
+      lockedBalance: BigInt(r.lockedBalance),
+      balance: BigInt(r.balance)
+    };
+  }
+  async bet(args) {
+    return this.txn("/ledger/bet", {
+      sessionToken: args.sessionToken,
+      transactionUuid: args.transactionUuid,
+      amount: args.amount.toString(),
+      round: args.round,
+      roundClosed: args.roundClosed
+    });
+  }
+  async win(args) {
+    return this.txn("/ledger/win", {
+      sessionToken: args.sessionToken,
+      transactionUuid: args.transactionUuid,
+      referenceTransactionUuid: args.referenceTransactionUuid,
+      amount: args.amount.toString(),
+      round: args.round,
+      roundClosed: args.roundClosed
+    });
+  }
+  async rollback(args) {
+    return this.txn("/ledger/rollback", {
+      sessionToken: args.sessionToken,
+      referenceTransactionUuid: args.referenceTransactionUuid,
+      round: args.round
+    });
+  }
+  async balance(sessionToken) {
+    const r = await this.call("/ledger/balance", { sessionToken });
+    return { balance: BigInt(r.balance), currency: r.currency };
+  }
+  async settleSession(sessionToken) {
+    const r = await this.call(
+      "/ledger/settle",
+      { sessionToken }
+    );
+    return { sessionId: r.sessionId, currency: r.currency, payout: BigInt(r.payout), railRef: r.railRef };
+  }
+  async txn(path, body) {
+    const r = await this.call(
+      path,
+      body
+    );
+    return { transactionUuid: r.transactionUuid, balance: BigInt(r.balance), currency: r.currency, applied: r.applied };
+  }
+};
+var SolvenServer = class {
+  constructor(options) {
+    if (!options.secretKey.startsWith("sk_")) {
+      throw new Error("SolvenServer requires a secret key (sk_...)");
+    }
+    this.secretKey = options.secretKey;
+    this.baseUrl = options.baseUrl.replace(/\/$/, "");
+    this.fetchImpl = options.fetchImpl ?? globalThis.fetch.bind(globalThis);
+    this.ledger = new LedgerApi((path, body) => this.call(path, body));
+  }
+  /**
+   * Verify a player's wallet session token server-to-server and return the canonical
+   * verified identity (scoped to this key's app + environment). Call this from your
+   * backend with the token your frontend received from the wallet, then mint your own
+   * app JWT for the returned user. Throws if the session is invalid or scoped elsewhere.
+   */
+  async verifySession(sessionToken) {
+    return this.call("/sessions/verify", { sessionToken });
+  }
+  async call(path, body) {
+    let resp;
+    try {
+      resp = await this.fetchImpl(`${this.baseUrl}${path}`, {
+        method: "POST",
+        headers: {
+          authorization: `Bearer ${this.secretKey}`,
+          "content-type": "application/json"
+        },
+        body: JSON.stringify(body ?? {})
+      });
+    } catch (err) {
+      throw new SolvenServerError({
+        code: "client/network",
+        message: err instanceof Error ? err.message : "network error",
+        httpStatus: 0
+      });
+    }
+    const text = await resp.text();
+    let json = void 0;
+    if (text) {
+      try {
+        json = JSON.parse(text);
+      } catch {
+        throw new SolvenServerError({
+          code: "client/bad_response",
+          message: `non-JSON response (${resp.status})`,
+          httpStatus: resp.status
+        });
+      }
+    }
+    if (!resp.ok) {
+      const env = json?.error;
+      if (env?.code) throw SolvenServerError.fromEnvelope(resp.status, env);
+      throw new SolvenServerError({
+        code: "client/bad_response",
+        message: `request failed (${resp.status})`,
+        httpStatus: resp.status
+      });
+    }
+    return json;
+  }
+};
+
+exports.IAMGameWalletServer = SolvenServer;
+exports.WalletServerError = SolvenServerError;

package/dist/index.d.cts

@@ -0,0 +1,137 @@
+type AuthMethod = "siws" | "telegram";
+interface IUserIdentity {
+    id: string;
+    type: AuthMethod;
+    /** For SIWS: base58 Solana pubkey. For Telegram: numeric user id as string. */
+    externalId: string;
+}
+interface IUserWallet {
+    /** base58 Solana pubkey */
+    address: string;
+    /** test (devnet) or live (mainnet) — wallets are isolated per environment. */
+    environment: "test" | "live";
+    custody: "self" | "operator";
+    status: "active" | "exported" | "archived";
+}
+/**
+ * Result of a server-to-server session verification (POST /v1/sessions/verify).
+ * A relying party (game backend) presents a player's wallet session token together
+ * with its own secret key; the wallet confirms the session, scopes it to the caller's
+ * app + environment, and returns the canonical user identity. The relying party then
+ * mints its OWN app JWT for its UI, trusting this verified identity.
+ */
+interface ISessionVerification {
+    userId: string;
+    appId: string;
+    environment: "test" | "live";
+    authMethod: AuthMethod;
+    /** Primary active wallet address for this user, or null if none provisioned yet. */
+    walletAddress: string | null;
+    wallets: IUserWallet[];
+    identities: IUserIdentity[];
+}
+
+type IAMGameErrorCode = "auth/invalid_signature" | "auth/challenge_expired" | "auth/challenge_already_redeemed" | "auth/invalid_init_data" | "auth/init_data_stale" | "auth/init_data_replayed" | "auth/missing_token" | "auth/invalid_token" | "auth/expired_token" | "wallet/not_found" | "wallet/insufficient_balance" | "wallet/export_blocked" | "wallet/already_exported" | "user/not_found" | "user/suspended" | "compliance/blocked" | "sign/invalid_transaction" | "sign/wallet_archived" | "sign/internal_failure" | "withdrawal/insufficient_balance" | "withdrawal/limit_exceeded" | "ledger/insufficient_balance" | "ledger/session_not_found" | "ledger/session_closed" | "ledger/bet_not_found" | "ledger/bet_rolled_back" | "ledger/currency_mismatch" | "ratelimit/exceeded" | "idempotency/key_in_use" | "validation/bad_request" | "server/internal";
+interface IIAMGameErrorEnvelope {
+    code: IAMGameErrorCode;
+    message: string;
+    details?: Record<string, unknown>;
+}
+
+interface IAMGameServerOptions {
+    /** Secret key, e.g. "sk_live_..." or "sk_test_...". */
+    secretKey: string;
+    /** Base URL incl. version path, e.g. "https://api-wallet.iamgame.com/v1". */
+    baseUrl: string;
+    fetchImpl?: typeof fetch;
+}
+interface OpenSessionArgs {
+    userId: string;
+    gameCode: string;
+    currency: string;
+    lockAmount: bigint;
+}
+interface OpenSessionResult {
+    sessionToken: string;
+    sessionId: string;
+    currency: string;
+    lockedBalance: bigint;
+    balance: bigint;
+}
+interface BetArgs {
+    sessionToken: string;
+    transactionUuid: string;
+    amount: bigint;
+    round?: string;
+    roundClosed?: boolean;
+}
+interface WinArgs {
+    sessionToken: string;
+    transactionUuid: string;
+    referenceTransactionUuid: string;
+    amount: bigint;
+    round?: string;
+    roundClosed?: boolean;
+}
+interface RollbackArgs {
+    sessionToken: string;
+    referenceTransactionUuid: string;
+    round?: string;
+}
+interface TxnResult {
+    transactionUuid: string;
+    balance: bigint;
+    currency: string;
+    applied: boolean;
+}
+interface BalanceResult {
+    balance: bigint;
+    currency: string;
+}
+interface SettleResult {
+    sessionId: string;
+    currency: string;
+    payout: bigint;
+    railRef: string | null;
+}
+declare class LedgerApi {
+    private readonly call;
+    constructor(call: <T>(path: string, body: unknown) => Promise<T>);
+    openSession(args: OpenSessionArgs): Promise<OpenSessionResult>;
+    bet(args: BetArgs): Promise<TxnResult>;
+    win(args: WinArgs): Promise<TxnResult>;
+    rollback(args: RollbackArgs): Promise<TxnResult>;
+    balance(sessionToken: string): Promise<BalanceResult>;
+    settleSession(sessionToken: string): Promise<SettleResult>;
+    private txn;
+}
+declare class IAMGameServer {
+    readonly ledger: LedgerApi;
+    private readonly secretKey;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(options: IAMGameServerOptions);
+    /**
+     * Verify a player's wallet session token server-to-server and return the canonical
+     * verified identity (scoped to this key's app + environment). Call this from your
+     * backend with the token your frontend received from the wallet, then mint your own
+     * app JWT for the returned user. Throws if the session is invalid or scoped elsewhere.
+     */
+    verifySession(sessionToken: string): Promise<ISessionVerification>;
+    private call;
+}
+
+declare class IAMGameServerError extends Error {
+    readonly code: IAMGameErrorCode | "client/network" | "client/bad_response";
+    readonly httpStatus: number;
+    readonly details?: Record<string, unknown>;
+    constructor(args: {
+        code: IAMGameServerError["code"];
+        message: string;
+        httpStatus: number;
+        details?: Record<string, unknown>;
+    });
+    static fromEnvelope(httpStatus: number, env: IIAMGameErrorEnvelope): IAMGameServerError;
+}
+
+export { type BalanceResult, type BetArgs, IAMGameServer as IAMGameWalletServer, type IAMGameServerOptions as IAMGameWalletServerOptions, type ISessionVerification, type OpenSessionArgs, type OpenSessionResult, type RollbackArgs, type SettleResult, type TxnResult, IAMGameServerError as WalletServerError, type WinArgs };

package/dist/index.d.ts

@@ -0,0 +1,137 @@
+type AuthMethod = "siws" | "telegram";
+interface IUserIdentity {
+    id: string;
+    type: AuthMethod;
+    /** For SIWS: base58 Solana pubkey. For Telegram: numeric user id as string. */
+    externalId: string;
+}
+interface IUserWallet {
+    /** base58 Solana pubkey */
+    address: string;
+    /** test (devnet) or live (mainnet) — wallets are isolated per environment. */
+    environment: "test" | "live";
+    custody: "self" | "operator";
+    status: "active" | "exported" | "archived";
+}
+/**
+ * Result of a server-to-server session verification (POST /v1/sessions/verify).
+ * A relying party (game backend) presents a player's wallet session token together
+ * with its own secret key; the wallet confirms the session, scopes it to the caller's
+ * app + environment, and returns the canonical user identity. The relying party then
+ * mints its OWN app JWT for its UI, trusting this verified identity.
+ */
+interface ISessionVerification {
+    userId: string;
+    appId: string;
+    environment: "test" | "live";
+    authMethod: AuthMethod;
+    /** Primary active wallet address for this user, or null if none provisioned yet. */
+    walletAddress: string | null;
+    wallets: IUserWallet[];
+    identities: IUserIdentity[];
+}
+
+type IAMGameErrorCode = "auth/invalid_signature" | "auth/challenge_expired" | "auth/challenge_already_redeemed" | "auth/invalid_init_data" | "auth/init_data_stale" | "auth/init_data_replayed" | "auth/missing_token" | "auth/invalid_token" | "auth/expired_token" | "wallet/not_found" | "wallet/insufficient_balance" | "wallet/export_blocked" | "wallet/already_exported" | "user/not_found" | "user/suspended" | "compliance/blocked" | "sign/invalid_transaction" | "sign/wallet_archived" | "sign/internal_failure" | "withdrawal/insufficient_balance" | "withdrawal/limit_exceeded" | "ledger/insufficient_balance" | "ledger/session_not_found" | "ledger/session_closed" | "ledger/bet_not_found" | "ledger/bet_rolled_back" | "ledger/currency_mismatch" | "ratelimit/exceeded" | "idempotency/key_in_use" | "validation/bad_request" | "server/internal";
+interface IIAMGameErrorEnvelope {
+    code: IAMGameErrorCode;
+    message: string;
+    details?: Record<string, unknown>;
+}
+
+interface IAMGameServerOptions {
+    /** Secret key, e.g. "sk_live_..." or "sk_test_...". */
+    secretKey: string;
+    /** Base URL incl. version path, e.g. "https://api-wallet.iamgame.com/v1". */
+    baseUrl: string;
+    fetchImpl?: typeof fetch;
+}
+interface OpenSessionArgs {
+    userId: string;
+    gameCode: string;
+    currency: string;
+    lockAmount: bigint;
+}
+interface OpenSessionResult {
+    sessionToken: string;
+    sessionId: string;
+    currency: string;
+    lockedBalance: bigint;
+    balance: bigint;
+}
+interface BetArgs {
+    sessionToken: string;
+    transactionUuid: string;
+    amount: bigint;
+    round?: string;
+    roundClosed?: boolean;
+}
+interface WinArgs {
+    sessionToken: string;
+    transactionUuid: string;
+    referenceTransactionUuid: string;
+    amount: bigint;
+    round?: string;
+    roundClosed?: boolean;
+}
+interface RollbackArgs {
+    sessionToken: string;
+    referenceTransactionUuid: string;
+    round?: string;
+}
+interface TxnResult {
+    transactionUuid: string;
+    balance: bigint;
+    currency: string;
+    applied: boolean;
+}
+interface BalanceResult {
+    balance: bigint;
+    currency: string;
+}
+interface SettleResult {
+    sessionId: string;
+    currency: string;
+    payout: bigint;
+    railRef: string | null;
+}
+declare class LedgerApi {
+    private readonly call;
+    constructor(call: <T>(path: string, body: unknown) => Promise<T>);
+    openSession(args: OpenSessionArgs): Promise<OpenSessionResult>;
+    bet(args: BetArgs): Promise<TxnResult>;
+    win(args: WinArgs): Promise<TxnResult>;
+    rollback(args: RollbackArgs): Promise<TxnResult>;
+    balance(sessionToken: string): Promise<BalanceResult>;
+    settleSession(sessionToken: string): Promise<SettleResult>;
+    private txn;
+}
+declare class IAMGameServer {
+    readonly ledger: LedgerApi;
+    private readonly secretKey;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(options: IAMGameServerOptions);
+    /**
+     * Verify a player's wallet session token server-to-server and return the canonical
+     * verified identity (scoped to this key's app + environment). Call this from your
+     * backend with the token your frontend received from the wallet, then mint your own
+     * app JWT for the returned user. Throws if the session is invalid or scoped elsewhere.
+     */
+    verifySession(sessionToken: string): Promise<ISessionVerification>;
+    private call;
+}
+
+declare class IAMGameServerError extends Error {
+    readonly code: IAMGameErrorCode | "client/network" | "client/bad_response";
+    readonly httpStatus: number;
+    readonly details?: Record<string, unknown>;
+    constructor(args: {
+        code: IAMGameServerError["code"];
+        message: string;
+        httpStatus: number;
+        details?: Record<string, unknown>;
+    });
+    static fromEnvelope(httpStatus: number, env: IIAMGameErrorEnvelope): IAMGameServerError;
+}
+
+export { type BalanceResult, type BetArgs, IAMGameServer as IAMGameWalletServer, type IAMGameServerOptions as IAMGameWalletServerOptions, type ISessionVerification, type OpenSessionArgs, type OpenSessionResult, type RollbackArgs, type SettleResult, type TxnResult, IAMGameServerError as WalletServerError, type WinArgs };

package/dist/index.js

@@ -0,0 +1,148 @@
+// ../../solven/sdk-server/src/errors.ts
+var SolvenServerError = class _SolvenServerError extends Error {
+  constructor(args) {
+    super(args.message);
+    this.name = "SolvenServerError";
+    this.code = args.code;
+    this.httpStatus = args.httpStatus;
+    this.details = args.details;
+  }
+  static fromEnvelope(httpStatus, env) {
+    return new _SolvenServerError({
+      code: env.code,
+      message: env.message,
+      httpStatus,
+      details: env.details
+    });
+  }
+};
+
+// ../../solven/sdk-server/src/client.ts
+var LedgerApi = class {
+  constructor(call) {
+    this.call = call;
+  }
+  async openSession(args) {
+    const r = await this.call("/ledger/sessions", {
+      userId: args.userId,
+      gameCode: args.gameCode,
+      currency: args.currency,
+      lockAmount: args.lockAmount.toString()
+    });
+    return {
+      sessionToken: r.sessionToken,
+      sessionId: r.sessionId,
+      currency: r.currency,
+      lockedBalance: BigInt(r.lockedBalance),
+      balance: BigInt(r.balance)
+    };
+  }
+  async bet(args) {
+    return this.txn("/ledger/bet", {
+      sessionToken: args.sessionToken,
+      transactionUuid: args.transactionUuid,
+      amount: args.amount.toString(),
+      round: args.round,
+      roundClosed: args.roundClosed
+    });
+  }
+  async win(args) {
+    return this.txn("/ledger/win", {
+      sessionToken: args.sessionToken,
+      transactionUuid: args.transactionUuid,
+      referenceTransactionUuid: args.referenceTransactionUuid,
+      amount: args.amount.toString(),
+      round: args.round,
+      roundClosed: args.roundClosed
+    });
+  }
+  async rollback(args) {
+    return this.txn("/ledger/rollback", {
+      sessionToken: args.sessionToken,
+      referenceTransactionUuid: args.referenceTransactionUuid,
+      round: args.round
+    });
+  }
+  async balance(sessionToken) {
+    const r = await this.call("/ledger/balance", { sessionToken });
+    return { balance: BigInt(r.balance), currency: r.currency };
+  }
+  async settleSession(sessionToken) {
+    const r = await this.call(
+      "/ledger/settle",
+      { sessionToken }
+    );
+    return { sessionId: r.sessionId, currency: r.currency, payout: BigInt(r.payout), railRef: r.railRef };
+  }
+  async txn(path, body) {
+    const r = await this.call(
+      path,
+      body
+    );
+    return { transactionUuid: r.transactionUuid, balance: BigInt(r.balance), currency: r.currency, applied: r.applied };
+  }
+};
+var SolvenServer = class {
+  constructor(options) {
+    if (!options.secretKey.startsWith("sk_")) {
+      throw new Error("SolvenServer requires a secret key (sk_...)");
+    }
+    this.secretKey = options.secretKey;
+    this.baseUrl = options.baseUrl.replace(/\/$/, "");
+    this.fetchImpl = options.fetchImpl ?? globalThis.fetch.bind(globalThis);
+    this.ledger = new LedgerApi((path, body) => this.call(path, body));
+  }
+  /**
+   * Verify a player's wallet session token server-to-server and return the canonical
+   * verified identity (scoped to this key's app + environment). Call this from your
+   * backend with the token your frontend received from the wallet, then mint your own
+   * app JWT for the returned user. Throws if the session is invalid or scoped elsewhere.
+   */
+  async verifySession(sessionToken) {
+    return this.call("/sessions/verify", { sessionToken });
+  }
+  async call(path, body) {
+    let resp;
+    try {
+      resp = await this.fetchImpl(`${this.baseUrl}${path}`, {
+        method: "POST",
+        headers: {
+          authorization: `Bearer ${this.secretKey}`,
+          "content-type": "application/json"
+        },
+        body: JSON.stringify(body ?? {})
+      });
+    } catch (err) {
+      throw new SolvenServerError({
+        code: "client/network",
+        message: err instanceof Error ? err.message : "network error",
+        httpStatus: 0
+      });
+    }
+    const text = await resp.text();
+    let json = void 0;
+    if (text) {
+      try {
+        json = JSON.parse(text);
+      } catch {
+        throw new SolvenServerError({
+          code: "client/bad_response",
+          message: `non-JSON response (${resp.status})`,
+          httpStatus: resp.status
+        });
+      }
+    }
+    if (!resp.ok) {
+      const env = json?.error;
+      if (env?.code) throw SolvenServerError.fromEnvelope(resp.status, env);
+      throw new SolvenServerError({
+        code: "client/bad_response",
+        message: `request failed (${resp.status})`,
+        httpStatus: resp.status
+      });
+    }
+    return json;
+  }
+};
+
+export { SolvenServer as IAMGameWalletServer, SolvenServerError as WalletServerError };

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@iamgame/wallet-sdk-server",
+  "version": "0.1.0",
+  "description": "IAMGame Wallet backend SDK — secret-key server-to-server client: verify wallet sessions and run the high-frequency money ledger.",
+  "license": "MIT",
+  "homepage": "https://wallet.iamgame.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/iamgame777/iamgame-mono.git",
+    "directory": "iamgame-wallet/sdk-server"
+  },
+  "keywords": [
+    "iamgame",
+    "wallet",
+    "solana",
+    "ledger",
+    "server",
+    "backend",
+    "web3"
+  ],
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup && node ../scripts/debrand-dts.mjs",
+    "watch": "tsup --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@solven/sdk-server": "*",
+    "@solven/types": "*",
+    "tsup": "^8.3.5",
+    "typescript": "^5"
+  }
+}