@chipi-stack/backend 14.0.0 → 14.1.1

package/dist/index.js

@@ -4,6 +4,7 @@ var shared = require('@chipi-stack/shared');
 var CryptoES = require('crypto-es');
 var starknet = require('starknet');
 var types = require('@chipi-stack/types');
+var core = require('@chipi-stack/core');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
@@ -33,7 +34,7 @@ var ChipiClient = class {
       const cleanUrl = this.customAlphaUrl.replace(/\/v\d+\/?$/, "").replace(/\/$/, "");
       return `${cleanUrl}/${version}`;
     }
-    return `https://celebrated-vision-production-66a5.up.railway.app/${version}`;
+    return `https://api.chipipay.com/${version}`;
   }
   /**
    * Add API version query parameters to track the API version being used
@@ -241,6 +242,7 @@ var ChipiWallets = class {
         userId,
         walletType = "CHIPI",
         // Default to CHIPI wallet
+        classHash: customClassHash,
         usePasskey,
         chain
       } = params;
@@ -256,8 +258,8 @@ var ChipiWallets = class {
       const provider = new starknet.RpcProvider({ nodeUrl: rpcUrl });
       const privateKeyAX = this.getPrivateKeyAX();
       const starkKeyPubAX = starknet.ec.starkCurve.getStarkKey(privateKeyAX);
-      const accountClassHash = walletType === "READY" ? shared.WALLET_CLASS_HASHES.READY : shared.WALLET_CLASS_HASHES.CHIPI;
       const constructorCallData = this.buildConstructorCallData(walletType, starkKeyPubAX);
+      const accountClassHash = customClassHash ?? (walletType === "READY" ? shared.WALLET_CLASS_HASHES.READY : shared.WALLET_CLASS_HASHES.CHIPI);
       const publicKey = starknet.hash.calculateContractAddressFromHash(
         starkKeyPubAX,
         accountClassHash,
@@ -272,8 +274,8 @@ var ChipiWallets = class {
           chain,
           publicKey,
           walletType,
-          starkKeyPubAX
-          // Needed for backend to build deployment data
+          starkKeyPubAX,
+          ...customClassHash && { classHash: customClassHash }
         }
       });
       const { typedData: typedData2, accountClassHash: accountClassHashResponse } = typedDataResponse;
@@ -397,7 +399,121 @@ var ChipiWallets = class {
     });
     return getBalanceResponse;
   }
+  /**
+   * Prepare a wallet upgrade (e.g., READY → CHIPI or CHIPI v29 → v33).
+   * Returns typed data that must be signed by the wallet owner.
+   */
+  async prepareWalletUpgrade(params, bearerToken) {
+    return this.client.post({
+      endpoint: `${shared.API_ENDPOINTS.CHIPI_WALLETS}/prepare-upgrade`,
+      bearerToken,
+      body: params
+    });
+  }
+  /**
+   * Execute a wallet upgrade after the owner has signed the typed data.
+   */
+  async executeWalletUpgrade(params, bearerToken) {
+    return this.client.post({
+      endpoint: `${shared.API_ENDPOINTS.CHIPI_WALLETS}/upgrade`,
+      bearerToken,
+      body: params
+    });
+  }
+};
+function unwrapPrepareResponse(response) {
+  if (!response || typeof response !== "object") {
+    throw new Error(
+      "Invalid response from /transactions/prepare-typed-data: response is not an object"
+    );
+  }
+  if ("typedData" in response) {
+    const resp = response;
+    if (!resp.typedData || typeof resp.typedData !== "object" || !("types" in resp.typedData) || !("message" in resp.typedData)) {
+      throw new Error(
+        "Invalid response from /transactions/prepare-typed-data: typedData structure is invalid"
+      );
+    }
+    return { typedData: resp.typedData, walletType: resp.walletType };
+  }
+  if ("types" in response && "message" in response) {
+    return { typedData: response };
+  }
+  const apiMessage = typeof response.message === "string" ? response.message : void 0;
+  throw new Error(
+    apiMessage ?? "Invalid response from /transactions/prepare-typed-data: typedData is missing"
+  );
+}
+function normalizeSignature(signature) {
+  if (Array.isArray(signature)) {
+    if (signature.length < 2) {
+      throw new Error(`Array signature must have at least 2 elements, got ${signature.length}`);
+    }
+    const r = signature[0];
+    const s = signature[1];
+    if (r == null || s == null) {
+      throw new Error(`Signature elements must not be null/undefined. Got r=${r}, s=${s}`);
+    }
+    return { r: String(r), s: String(s) };
+  }
+  if (signature && typeof signature === "object" && "r" in signature && "s" in signature) {
+    const sig = signature;
+    if (sig.r == null || sig.s == null) {
+      throw new Error(`Object signature has null/undefined fields. Got r=${sig.r}, s=${sig.s}`);
+    }
+    return {
+      r: String(sig.r),
+      s: String(sig.s)
+    };
+  }
+  throw new Error("Unrecognized signature format from account.signMessage()");
+}
+var ChipiPaymasterAdapter = class {
+  constructor(client, bearerToken) {
+    this.client = client;
+    this.bearerToken = bearerToken;
+  }
+  async execute({ account, calls }) {
+    const classHash = await account.getClassHashAt(account.address);
+    const walletType = shared.getWalletTypeFromClassHash(classHash);
+    const accountClassHash = walletType ? shared.WALLET_CLASS_HASHES[walletType] : classHash;
+    const prepareResponse = await this.client.post({
+      endpoint: "/transactions/prepare-typed-data",
+      bearerToken: this.bearerToken,
+      body: {
+        publicKey: account.address,
+        calls,
+        accountClassHash
+      }
+    });
+    const { typedData: typedData2, walletType: resolvedWalletType } = unwrapPrepareResponse(prepareResponse);
+    const signature = await account.signMessage(typedData2);
+    const normalizedSig = normalizeSignature(signature);
+    const result = await this.client.post({
+      endpoint: "/transactions/execute-sponsored-transaction",
+      bearerToken: this.bearerToken,
+      body: {
+        publicKey: account.address,
+        typedData: typedData2,
+        userSignature: normalizedSig,
+        walletType: resolvedWalletType ?? walletType,
+        saveToDatabase: true
+      }
+    });
+    if (!result || typeof result !== "object") {
+      throw new Error(
+        "Invalid response from /transactions/execute-sponsored-transaction: response is not an object"
+      );
+    }
+    const apiMessage = typeof result.message === "string" ? result.message : void 0;
+    if (!result.transactionHash) {
+      throw new Error(apiMessage ?? "Response does not contain transaction hash");
+    }
+    return result.transactionHash;
+  }
 };
+
+// src/execute-paymaster-transaction.ts
 var executePaymasterTransaction = async ({
   params,
   bearerToken,
@@ -410,8 +526,10 @@ var executePaymasterTransaction = async ({
         usePasskey ? "encryptKey is required when using passkey. The passkey authentication should have provided the encryptKey." : "encryptKey is required for transaction execution"
       );
     }
-    const rpcUrl = shared.WALLET_RPC_ENDPOINTS.READY;
-    const accountClassHash = shared.WALLET_CLASS_HASHES.READY;
+    const walletType = wallet.walletType ?? "READY";
+    const isKnownType = Object.prototype.hasOwnProperty.call(shared.WALLET_RPC_ENDPOINTS, walletType) && Object.prototype.hasOwnProperty.call(shared.WALLET_CLASS_HASHES, walletType);
+    const rpcUrl = isKnownType ? shared.WALLET_RPC_ENDPOINTS[walletType] : shared.WALLET_RPC_ENDPOINTS["CHIPI"];
+    const accountClassHash = isKnownType ? shared.WALLET_CLASS_HASHES[walletType] : shared.WALLET_CLASS_HASHES["CHIPI"];
     let privateKeyDecrypted;
     try {
       privateKeyDecrypted = decryptPrivateKey(wallet.encryptedPrivateKey, encryptKey);
@@ -439,42 +557,47 @@ var executePaymasterTransaction = async ({
       );
     }
     let typedData2;
-    let walletType;
+    let resolvedWalletType;
     if ("typedData" in prepareResponse) {
       const resp = prepareResponse;
       typedData2 = resp.typedData;
-      walletType = resp.walletType;
+      if (resp.walletType && Object.prototype.hasOwnProperty.call(shared.WALLET_CLASS_HASHES, resp.walletType)) {
+        resolvedWalletType = resp.walletType;
+      }
     } else if (prepareResponse && "types" in prepareResponse && "message" in prepareResponse) {
       typedData2 = prepareResponse;
     } else {
-      const apiMessage = prepareResponse && typeof prepareResponse.message === "string" ? prepareResponse.message : void 0;
+      const apiMessage2 = prepareResponse && typeof prepareResponse.message === "string" ? prepareResponse.message : void 0;
       throw new Error(
-        apiMessage ?? "Invalid response from /transactions/prepare-typed-data: typedData is missing. This may occur for older STARKNET wallets that don't support paymaster transactions. Please ensure the wallet is a CHIPI wallet type."
+        apiMessage2 ?? "Invalid response from /transactions/prepare-typed-data: typedData is missing. This may occur for older STARKNET wallets that don't support paymaster transactions. Please ensure the wallet is a CHIPI wallet type."
       );
     }
-    if (!typedData2 || typeof typedData2 !== "object" || !("message" in typedData2)) {
+    if (!typedData2 || typeof typedData2 !== "object" || !("types" in typedData2) || !("message" in typedData2)) {
       throw new Error(
-        "Invalid typedData received from backend: missing 'message' field. This may occur for older STARKNET wallets that don't support paymaster transactions."
+        "Invalid typedData received from backend: missing 'types' or 'message' field. This may occur for older STARKNET wallets that don't support paymaster transactions."
       );
     }
     const userSignature = await account.signMessage(typedData2);
+    const normalizedSig = normalizeSignature(userSignature);
     const result = await client.post({
       endpoint: "/transactions/execute-sponsored-transaction",
       bearerToken,
       body: {
         publicKey: wallet.publicKey,
         typedData: typedData2,
-        userSignature: {
-          r: userSignature.r.toString(),
-          s: userSignature.s.toString(),
-          recovery: userSignature.recovery
-        },
+        userSignature: normalizedSig,
         saveToDatabase,
-        walletType
+        walletType: resolvedWalletType ?? walletType
       }
     });
-    if (!result.transactionHash) {
-      throw new Error("The response does not contain the transaction hash");
+    if (!result || typeof result !== "object") {
+      throw new Error(
+        "Invalid response from /transactions/execute-sponsored-transaction: response is not an object"
+      );
+    }
+    const apiMessage = typeof result.message === "string" ? result.message : void 0;
+    if (typeof result.transactionHash !== "string" || result.transactionHash.trim().length === 0) {
+      throw new Error(apiMessage ?? "Response does not contain transaction hash");
     }
     return result.transactionHash;
   } catch (error) {
@@ -540,7 +663,7 @@ var executePaymasterTransactionWithSession = async ({
       );
     }
     const accountClassHash = shared.WALLET_CLASS_HASHES.CHIPI;
-    const typeDataResult = await client.post({
+    const prepareResponse = await client.post({
       endpoint: "/transactions/prepare-typed-data",
       bearerToken,
       body: {
@@ -550,7 +673,31 @@ var executePaymasterTransactionWithSession = async ({
         walletType: "CHIPI"
       }
     });
-    const msgHash = starknet.typedData.getMessageHash(typeDataResult, wallet.publicKey);
+    if (!prepareResponse || typeof prepareResponse !== "object") {
+      throw new shared.ChipiSessionError(
+        "Invalid response from /transactions/prepare-typed-data: response is not an object",
+        shared.SESSION_ERRORS.SESSION_INVALID_RESPONSE
+      );
+    }
+    let sessionTypedData;
+    if ("typedData" in prepareResponse && prepareResponse.typedData) {
+      const candidate = prepareResponse.typedData;
+      if (!candidate || typeof candidate !== "object" || !("types" in candidate) || !("message" in candidate)) {
+        throw new shared.ChipiSessionError(
+          "Invalid response from /transactions/prepare-typed-data: typedData structure is invalid",
+          shared.SESSION_ERRORS.SESSION_INVALID_RESPONSE
+        );
+      }
+      sessionTypedData = candidate;
+    } else if ("types" in prepareResponse && "message" in prepareResponse) {
+      sessionTypedData = prepareResponse;
+    } else {
+      throw new shared.ChipiSessionError(
+        "Invalid response from /transactions/prepare-typed-data: typedData is missing",
+        shared.SESSION_ERRORS.SESSION_INVALID_RESPONSE
+      );
+    }
+    const msgHash = starknet.typedData.getMessageHash(sessionTypedData, wallet.publicKey);
     const { r, s } = starknet.ec.starkCurve.sign(msgHash, sessionPrivateKey);
     const sessionSignature = [
       session.publicKey,
@@ -563,7 +710,7 @@ var executePaymasterTransactionWithSession = async ({
       bearerToken,
       body: {
         publicKey: wallet.publicKey,
-        typeData: typeDataResult,
+        typedData: sessionTypedData,
         // Session signature format - array of 4 hex strings
         userSignature: sessionSignature,
         saveToDatabase,
@@ -572,11 +719,21 @@ var executePaymasterTransactionWithSession = async ({
         // Flag to indicate session signature format
       }
     });
-    if (!result.transactionHash) {
+    if (!result || typeof result !== "object") {
+      throw new shared.ChipiSessionError(
+        "Invalid response from /transactions/execute-sponsored-transaction: response is not an object",
+        shared.SESSION_ERRORS.SESSION_INVALID_RESPONSE
+      );
+    }
+    if (typeof result.transactionHash !== "string" || result.transactionHash.trim().length === 0) {
+      const apiMessage = typeof result.message === "string" ? result.message : void 0;
       console.error("[ChipiSDK:Session:Execute] No transaction hash in response", {
         result
       });
-      throw new Error("Response does not contain transaction hash");
+      throw new shared.ChipiSessionError(
+        apiMessage ?? "Response does not contain transaction hash",
+        shared.SESSION_ERRORS.SESSION_INVALID_RESPONSE
+      );
     }
     return result.transactionHash;
   } catch (error) {
@@ -714,6 +871,24 @@ var ChipiTransactions = class {
     });
     return response;
   }
+  /**
+   * Get a single transaction by hash or internal ID
+   */
+  async getTransaction(hashOrId, bearerToken) {
+    return this.client.get({
+      endpoint: `${shared.API_ENDPOINTS.TRANSACTIONS}/${hashOrId}`,
+      bearerToken
+    });
+  }
+  /**
+   * Get on-chain transaction status
+   */
+  async getTransactionStatus(hash3, bearerToken) {
+    return this.client.get({
+      endpoint: `${shared.API_ENDPOINTS.TRANSACTIONS}/${hash3}/status`,
+      bearerToken
+    });
+  }
 };
 var ChipiExchanges = class {
   constructor(client) {
@@ -1250,6 +1425,240 @@ var ChipiSessions = class {
     });
   }
 };
+var InMemoryNonceStore = class {
+  constructor() {
+    this.used = /* @__PURE__ */ new Set();
+  }
+  has(nonce) {
+    return this.used.has(nonce);
+  }
+  consume(nonce) {
+    if (this.used.has(nonce)) return false;
+    this.used.add(nonce);
+    return true;
+  }
+};
+var X402Facilitator = class _X402Facilitator {
+  constructor(client, bearerToken, config) {
+    this.client = client;
+    this.bearerToken = bearerToken;
+    this.nonceStore = config?.nonceStore ?? new InMemoryNonceStore();
+    this.provider = config?.provider;
+  }
+  /**
+   * Factory method for simpler instantiation.
+   *
+   * @example
+   * ```typescript
+   * const facilitator = X402Facilitator.create({
+   *   apiKey: process.env.CHIPI_API_KEY!,
+   *   bearerToken: process.env.CHIPI_BEARER_TOKEN!,
+   * });
+   * ```
+   */
+  static create(options) {
+    const client = new ChipiClient({ apiPublicKey: options.apiKey });
+    return new _X402Facilitator(client, options.bearerToken, {
+      nonceStore: options.nonceStore,
+      provider: options.provider
+    });
+  }
+  /**
+   * Verify a payment signature is valid (doesn't execute the transfer).
+   *
+   * Checks:
+   * 1. Nonce has not been used (replay protection)
+   * 2. Payment has not expired (validUntil > now)
+   * 3. Asset is USDC mainnet
+   * 4. Amount is positive
+   * 5. Addresses are non-empty
+   */
+  async verify(payment) {
+    const { payload } = payment;
+    if (payment.x402Version !== 1) {
+      return { isValid: false, invalidReason: `Unsupported x402 version: ${payment.x402Version}` };
+    }
+    if (payment.network !== "starknet-mainnet") {
+      return { isValid: false, invalidReason: `Unsupported network: ${payment.network}` };
+    }
+    if (await this.nonceStore.has(payload.nonce)) {
+      return { isValid: false, invalidReason: "Nonce already used (replay)" };
+    }
+    const now = Math.floor(Date.now() / 1e3);
+    if (payload.validUntil <= now) {
+      return { isValid: false, invalidReason: "Payment has expired (validUntil in the past)" };
+    }
+    const normalizedAsset = payload.asset.toLowerCase().replace(/^0x0+/, "0x");
+    const normalizedUsdc = shared.CONTRACT_ADDRESSES.USDC_MAINNET.toLowerCase().replace(/^0x0+/, "0x");
+    if (normalizedAsset !== normalizedUsdc) {
+      return {
+        isValid: false,
+        invalidReason: `Unsupported asset: ${payload.asset}. Only USDC is accepted.`
+      };
+    }
+    let amount;
+    try {
+      amount = BigInt(payload.amount);
+    } catch {
+      return { isValid: false, invalidReason: "Invalid payment amount format" };
+    }
+    if (amount <= 0n) {
+      return { isValid: false, invalidReason: "Payment amount must be positive" };
+    }
+    if (!payload.fromAddress || !payload.toAddress) {
+      return { isValid: false, invalidReason: "Missing fromAddress or toAddress" };
+    }
+    const sigResult = await this.verifySignature(payment);
+    if (!sigResult.valid) {
+      return { isValid: false, invalidReason: sigResult.reason };
+    }
+    return { isValid: true };
+  }
+  /**
+   * Verify the SNIP-12 signature on a payment payload.
+   *
+   * If an RPC provider is configured, reconstructs the typed data, computes the
+   * message hash, and calls `is_valid_signature()` on the sender's account contract.
+   * Otherwise falls back to a presence-only check (backwards compatible).
+   */
+  async verifySignature(payment) {
+    if (!this.provider) {
+      if (!payment.payload?.signature?.r || !payment.payload?.signature?.s) {
+        return { valid: false, reason: "Missing signature" };
+      }
+      return { valid: true };
+    }
+    const payload = payment.payload;
+    if (!payload?.signature?.r || !payload?.signature?.s) {
+      return { valid: false, reason: "Missing signature" };
+    }
+    const paymentTypedData = core.buildX402TypedData({
+      from_address: payload.fromAddress,
+      to_address: payload.toAddress,
+      amount: payload.amount,
+      asset: payload.asset,
+      valid_until: String(payload.validUntil),
+      nonce: payload.nonce
+    });
+    const msgHash = starknet.typedData.getMessageHash(paymentTypedData, payload.fromAddress);
+    try {
+      const result = await this.provider.callContract({
+        contractAddress: payload.fromAddress,
+        entrypoint: "is_valid_signature",
+        calldata: [msgHash, "2", payload.signature.r, payload.signature.s]
+      });
+      const VALID = "0x56414c4944";
+      if (result[0] === VALID || result[0] === BigInt(VALID).toString()) {
+        return { valid: true };
+      }
+      return { valid: false, reason: "Invalid SNIP-12 signature" };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return { valid: false, reason: `Signature verification failed: ${message}` };
+    }
+  }
+  /**
+   * Settle a verified payment by executing the USDC transfer via paymaster.
+   *
+   * IMPORTANT: Mark nonce as consumed BEFORE executing to prevent concurrent replays.
+   * If the transfer fails after nonce consumption, the nonce is still burned
+   * (caller should implement idempotency at a higher level if needed).
+   */
+  async settle(payment) {
+    const { payload } = payment;
+    const verification = await this.verify(payment);
+    if (!verification.isValid) {
+      return { success: false, errorReason: verification.invalidReason };
+    }
+    const consumed = await this.nonceStore.consume(payload.nonce);
+    if (!consumed) {
+      return { success: false, errorReason: "Nonce already consumed (concurrent replay)" };
+    }
+    try {
+      const amountU256 = starknet.uint256.bnToUint256(BigInt(payload.amount));
+      const transferCall = {
+        contractAddress: payload.asset,
+        entrypoint: "transfer",
+        calldata: [payload.toAddress, amountU256.low.toString(), amountU256.high.toString()]
+      };
+      const prepareResponse = await this.client.post({
+        endpoint: "/transactions/prepare-typed-data",
+        bearerToken: this.bearerToken,
+        body: {
+          publicKey: payload.fromAddress,
+          calls: [transferCall]
+        }
+      });
+      const result = await this.client.post({
+        endpoint: "/transactions/execute-sponsored-transaction",
+        bearerToken: this.bearerToken,
+        body: {
+          publicKey: payload.fromAddress,
+          typedData: prepareResponse.typedData,
+          userSignature: payload.signature,
+          walletType: prepareResponse.walletType,
+          saveToDatabase: true
+        }
+      });
+      if (typeof result?.transactionHash !== "string" || !result.transactionHash.trim()) {
+        return {
+          success: false,
+          errorReason: result?.message ?? "No transaction hash returned from paymaster"
+        };
+      }
+      return {
+        success: true,
+        transactionHash: result.transactionHash,
+        networkId: "starknet-mainnet"
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return {
+        success: false,
+        errorReason: `Settlement failed: ${message}`
+      };
+    }
+  }
+};
+var signTypedData = async ({
+  params
+}) => {
+  try {
+    const { encryptKey, wallet, typedData: typedData2 } = params;
+    if (!encryptKey) {
+      throw new Error("encryptKey is required for signing typed data");
+    }
+    if (!wallet || !wallet.encryptedPrivateKey || !wallet.publicKey) {
+      throw new Error("wallet with publicKey and encryptedPrivateKey is required");
+    }
+    if (!typedData2) {
+      throw new Error("typedData is required for signing");
+    }
+    const walletType = wallet.walletType ?? "READY";
+    if (!Object.prototype.hasOwnProperty.call(shared.WALLET_RPC_ENDPOINTS, walletType) || !Object.prototype.hasOwnProperty.call(shared.WALLET_CLASS_HASHES, walletType)) {
+      throw new Error(`Unsupported wallet type: "${String(walletType)}"`);
+    }
+    const rpcUrl = shared.WALLET_RPC_ENDPOINTS[walletType];
+    let privateKeyDecrypted;
+    try {
+      privateKeyDecrypted = decryptPrivateKey(wallet.encryptedPrivateKey, encryptKey);
+    } catch {
+      throw new Error("Failed to decrypt private key. Verify the encryptKey is correct.");
+    }
+    const provider = new starknet.RpcProvider({ nodeUrl: rpcUrl });
+    const account = new starknet.Account({
+      provider,
+      address: wallet.publicKey,
+      signer: privateKeyDecrypted
+    });
+    const signature = await account.signMessage(typedData2);
+    const normalizedSig = normalizeSignature(signature);
+    return normalizedSig;
+  } catch (error) {
+    console.error("Error signing typed data", error);
+    throw error;
+  }
+};
 
 // src/chipi-sdk.ts
 var ChipiSDK = class {
@@ -1272,6 +1681,9 @@ var ChipiSDK = class {
     this.recordSendTransaction = this.recordSendTransaction.bind(this);
     this.purchaseSku = this.purchaseSku.bind(this);
     this.getUsdAmount = this.getUsdAmount.bind(this);
+    this.signTypedData = this.signTypedData.bind(this);
+    this.createPaymasterAdapter = this.createPaymasterAdapter.bind(this);
+    this.createX402Facilitator = this.createX402Facilitator.bind(this);
   }
   /**
    * Resolve bearer token - uses provided token or falls back to apiSecretKey
@@ -1285,6 +1697,43 @@ var ChipiSDK = class {
     }
     return token;
   }
+  /**
+   * Create a PaymasterAdapter for use with TxBuilder.sendSponsored().
+   *
+   * @example
+   * ```typescript
+   * const sdk = new ChipiServerSDK({ apiPublicKey: "pk_...", apiSecretKey: "sk_..." });
+   * const paymaster = sdk.createPaymasterAdapter();
+   *
+   * const txHash = await new TxBuilder(account, { paymaster })
+   *   .transfer(USDC, [{ to, amount }])
+   *   .sendSponsored(); // gasless!
+   * ```
+   */
+  createPaymasterAdapter(bearerToken) {
+    const token = this.resolveBearerToken(bearerToken);
+    return new ChipiPaymasterAdapter(this.client, token);
+  }
+  /**
+   * Create an X402Facilitator for verifying and settling x402 payments.
+   *
+   * @example
+   * ```typescript
+   * const facilitator = sdk.createX402Facilitator();
+   *
+   * // With custom nonce store (Redis)
+   * const facilitator = sdk.createX402Facilitator(bearerToken, {
+   *   nonceStore: {
+   *     has: async (nonce) => (await redis.sismember("x402:nonces", nonce)) === 1,
+   *     consume: async (nonce) => (await redis.sadd("x402:nonces", nonce)) === 1,
+   *   },
+   * });
+   * ```
+   */
+  createX402Facilitator(bearerToken, config) {
+    const token = this.resolveBearerToken(bearerToken);
+    return new X402Facilitator(this.client, token, config);
+  }
   /**
    * Execute a gasless transaction
    */
@@ -1340,6 +1789,29 @@ var ChipiSDK = class {
       this.resolveBearerToken(bearerToken)
     );
   }
+  /**
+   * Sign SNIP-12 typed data without executing a transaction.
+   *
+   * Purely local operation: decrypt private key → sign → return { r, s }.
+   * No API calls are made. Useful for x402 payment signatures and other
+   * off-chain signing flows.
+   *
+   * @example
+   * ```typescript
+   * const { r, s } = await sdk.signTypedData({
+   *   params: {
+   *     encryptKey: pin,
+   *     wallet,
+   *     typedData: snip12TypedData,
+   *   },
+   * });
+   * ```
+   */
+  async signTypedData({
+    params
+  }) {
+    return signTypedData({ params });
+  }
   /**
    * Transfer tokens
    */
@@ -1447,6 +1919,33 @@ var ChipiSDK = class {
   async getSku(id, bearerToken) {
     return this.skus.getSku(id, this.resolveBearerToken(bearerToken));
   }
+  /**
+   * Get a single transaction by hash or internal ID
+   */
+  async getTransaction(hashOrId, bearerToken) {
+    return this.transactions.getTransaction(hashOrId, this.resolveBearerToken(bearerToken));
+  }
+  /**
+   * Get on-chain transaction status (supports polling for confirmation)
+   */
+  async getTransactionStatus(hash3, bearerToken) {
+    return this.transactions.getTransactionStatus(hash3, this.resolveBearerToken(bearerToken));
+  }
+  /**
+   * Prepare a wallet upgrade (e.g., READY → CHIPI or CHIPI v29 → v33).
+   * Returns typed data that must be signed by the wallet owner.
+   * Server-only: requires API secret key.
+   */
+  async prepareWalletUpgrade(params, bearerToken) {
+    return this.wallets.prepareWalletUpgrade(params, this.resolveBearerToken(bearerToken));
+  }
+  /**
+   * Execute a wallet upgrade after signing.
+   * Server-only: requires API secret key.
+   */
+  async executeWalletUpgrade(params, bearerToken) {
+    return this.wallets.executeWalletUpgrade(params, this.resolveBearerToken(bearerToken));
+  }
   async getUsdAmount(currencyAmount, currency, bearerToken) {
     return this.exchanges.getUsdAmount(
       currencyAmount,
@@ -1478,6 +1977,129 @@ var ChipiBrowserSDK = class extends ChipiSDK {
   // All methods are inherited from ChipiSDK
   // bearerToken parameter is required for each authenticated request
 };
+function amountToBaseUnits(amount, decimals) {
+  const [whole, frac = ""] = amount.split(".");
+  const fracPadded = (frac + "0".repeat(decimals)).slice(0, decimals);
+  return String(BigInt(whole + fracPadded));
+}
+function buildPaymentRequirement(config, resource) {
+  const amountBaseUnits = amountToBaseUnits(config.amount, shared.TOKEN_DECIMALS.USDC);
+  return {
+    scheme: "exact",
+    network: "starknet-mainnet",
+    maxAmountRequired: amountBaseUnits,
+    resource,
+    description: config.description,
+    payTo: config.payTo,
+    maxTimeoutSeconds: 300,
+    asset: shared.CONTRACT_ADDRESSES.USDC_MAINNET
+  };
+}
+function isFlatConfig(config) {
+  return "amount" in config && "recipient" in config;
+}
+function resolveConfig(config) {
+  if (isFlatConfig(config)) {
+    return {
+      facilitator: config.facilitator,
+      paymentConfig: {
+        amount: config.amount,
+        payTo: config.recipient,
+        description: config.description
+      },
+      verifyOnly: config.verifyOnly
+    };
+  }
+  return config;
+}
+function x402Middleware(config) {
+  const resolved = resolveConfig(config);
+  return async (req, res, next) => {
+    if (req.method === "OPTIONS") {
+      return next();
+    }
+    const paymentHeader = req.headers?.["x-payment"] ?? req.headers?.["X-PAYMENT"];
+    if (!paymentHeader) {
+      const resource = req.protocol && req.get ? `${req.protocol}://${req.get("host")}${req.originalUrl}` : req.url ?? "";
+      const requirement2 = buildPaymentRequirement(resolved.paymentConfig, resource);
+      return res.status(402).set("Payment-Required", JSON.stringify(requirement2)).json({
+        error: "Payment Required",
+        paymentRequirement: requirement2
+      });
+    }
+    let payment;
+    try {
+      payment = typeof paymentHeader === "string" ? JSON.parse(paymentHeader) : paymentHeader;
+    } catch {
+      return res.status(400).json({ error: "Malformed X-PAYMENT header: invalid JSON" });
+    }
+    const payload = payment?.payload;
+    const toAddress = typeof payload?.toAddress === "string" ? payload.toAddress : null;
+    const amount = typeof payload?.amount === "string" ? payload.amount : null;
+    const asset = typeof payload?.asset === "string" ? payload.asset : null;
+    if (!toAddress || !amount || !asset) {
+      return res.status(400).json({ error: "Malformed X-PAYMENT payload: missing required fields" });
+    }
+    const requirement = buildPaymentRequirement(resolved.paymentConfig, "");
+    const normalizeAddr = (a) => a.toLowerCase().replace(/^0x0+/, "0x");
+    if (normalizeAddr(toAddress) !== normalizeAddr(resolved.paymentConfig.payTo)) {
+      return res.status(402).json({
+        error: "Payment recipient mismatch",
+        reason: `Expected ${resolved.paymentConfig.payTo}, got ${toAddress}`
+      });
+    }
+    let paidAmount;
+    try {
+      paidAmount = BigInt(amount);
+    } catch {
+      return res.status(400).json({ error: "Malformed X-PAYMENT payload", reason: "amount must be an integer string" });
+    }
+    if (paidAmount < BigInt(requirement.maxAmountRequired)) {
+      return res.status(402).json({
+        error: "Payment amount insufficient",
+        reason: `Required ${requirement.maxAmountRequired} base units, got ${amount}`
+      });
+    }
+    if (normalizeAddr(asset) !== normalizeAddr(requirement.asset)) {
+      return res.status(402).json({
+        error: "Payment asset mismatch",
+        reason: `Expected USDC, got ${asset}`
+      });
+    }
+    try {
+      const verified = await resolved.facilitator.verify(payment);
+      if (!verified.isValid) {
+        return res.status(402).json({
+          error: "Payment verification failed",
+          reason: verified.invalidReason
+        });
+      }
+      if (!resolved.verifyOnly) {
+        const settled = await resolved.facilitator.settle(payment);
+        if (!settled.success) {
+          return res.status(402).json({
+            error: "Payment settlement failed",
+            reason: settled.errorReason
+          });
+        }
+        req.x402 = {
+          txHash: settled.transactionHash,
+          payment,
+          networkId: settled.networkId
+        };
+      } else {
+        req.x402 = { payment };
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return res.status(500).json({
+        error: "Payment processing error",
+        reason: message
+      });
+    }
+    next();
+  };
+}
 
 Object.defineProperty(exports, "Chain", {
   enumerable: true,
@@ -1489,6 +2111,7 @@ Object.defineProperty(exports, "ChainToken", {
 });
 exports.ChipiBrowserSDK = ChipiBrowserSDK;
 exports.ChipiClient = ChipiClient;
+exports.ChipiPaymasterAdapter = ChipiPaymasterAdapter;
 exports.ChipiSDK = ChipiSDK;
 exports.ChipiServerSDK = ChipiServerSDK;
 exports.ChipiSessions = ChipiSessions;
@@ -1496,7 +2119,10 @@ exports.ChipiSkuPurchases = ChipiSkuPurchases;
 exports.ChipiSkus = ChipiSkus;
 exports.ChipiTransactions = ChipiTransactions;
 exports.ChipiWallets = ChipiWallets;
+exports.X402Facilitator = X402Facilitator;
 exports.decryptPrivateKey = decryptPrivateKey;
 exports.encryptPrivateKey = encryptPrivateKey;
+exports.signTypedData = signTypedData;
+exports.x402Middleware = x402Middleware;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map