orbis1-sdk-rn 0.0.9 → 0.2.0

package/lib/typescript/src/types/SDKConfig.d.ts

@@ -15,6 +15,8 @@ export interface WalletConfig {
     enabled: boolean;
     /** Wallet keys (mnemonic, xpubs, etc.) */
     keys: Keys;
+    /** Absolute path to directory where wallet data will be stored. If not provided, defaults to app documents directory. */
+    dataDir?: string;
     /** Supported asset schemas */
     supportedSchemas?: AssetSchema[];
     /** Maximum allocations per UTXO */
@@ -102,9 +104,13 @@ export declare const SDKOptionsSchema: z.ZodObject<{
 }>;
 /**
  * Zod schema for SDK configuration
+ *
+ * Note: `apiKey` is intentionally omitted here — it is validated manually in
+ * `validateSDKConfig` so it can be optional when Gas-Free / Watch Tower are off.
+ * Including it in Zod led to stale builds or edge cases surfacing as
+ * "apiKey: API key is required".
  */
 export declare const SDKConfigSchema: z.ZodObject<{
-    apiKey: z.ZodString;
     environment: z.ZodDefault<z.ZodNativeEnum<typeof Environment>>;
     features: z.ZodOptional<z.ZodObject<{
         gasFree: z.ZodOptional<z.ZodObject<{
@@ -187,13 +193,9 @@ export declare const SDKConfigSchema: z.ZodObject<{
     }, {
         strictMode?: boolean | undefined;
     }>>;
-}, "strip", z.ZodTypeAny, {
-    apiKey: string;
-    environment: Environment;
-    options?: {
-        strictMode?: boolean | undefined;
-    } | undefined;
-    features?: z.objectOutputType<{
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    environment: z.ZodDefault<z.ZodNativeEnum<typeof Environment>>;
+    features: z.ZodOptional<z.ZodObject<{
         gasFree: z.ZodOptional<z.ZodObject<{
             enabled: z.ZodOptional<z.ZodBoolean>;
             timeout: z.ZodOptional<z.ZodNumber>;
@@ -214,18 +216,69 @@ export declare const SDKConfigSchema: z.ZodObject<{
             enabled?: boolean | undefined;
             pollingInterval?: number | undefined;
         }>>;
-    }, z.ZodTypeAny, "passthrough"> | undefined;
-    logging?: {
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        gasFree: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodOptional<z.ZodBoolean>;
+            timeout: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            enabled?: boolean | undefined;
+            timeout?: number | undefined;
+        }, {
+            enabled?: boolean | undefined;
+            timeout?: number | undefined;
+        }>>;
+        watchTower: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodOptional<z.ZodBoolean>;
+            pollingInterval: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            enabled?: boolean | undefined;
+            pollingInterval?: number | undefined;
+        }, {
+            enabled?: boolean | undefined;
+            pollingInterval?: number | undefined;
+        }>>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        gasFree: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodOptional<z.ZodBoolean>;
+            timeout: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            enabled?: boolean | undefined;
+            timeout?: number | undefined;
+        }, {
+            enabled?: boolean | undefined;
+            timeout?: number | undefined;
+        }>>;
+        watchTower: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodOptional<z.ZodBoolean>;
+            pollingInterval: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            enabled?: boolean | undefined;
+            pollingInterval?: number | undefined;
+        }, {
+            enabled?: boolean | undefined;
+            pollingInterval?: number | undefined;
+        }>>;
+    }, z.ZodTypeAny, "passthrough">>>;
+    logging: z.ZodOptional<z.ZodObject<{
+        level: z.ZodOptional<z.ZodNativeEnum<typeof LogLevel>>;
+        logger: z.ZodOptional<z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
         level?: LogLevel | undefined;
         logger?: ((...args: unknown[]) => unknown) | undefined;
-    } | undefined;
-}, {
-    apiKey: string;
-    options?: {
+    }, {
+        level?: LogLevel | undefined;
+        logger?: ((...args: unknown[]) => unknown) | undefined;
+    }>>;
+    options: z.ZodOptional<z.ZodObject<{
+        strictMode: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
         strictMode?: boolean | undefined;
-    } | undefined;
-    environment?: Environment | undefined;
-    features?: z.objectInputType<{
+    }, {
+        strictMode?: boolean | undefined;
+    }>>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    environment: z.ZodDefault<z.ZodNativeEnum<typeof Environment>>;
+    features: z.ZodOptional<z.ZodObject<{
         gasFree: z.ZodOptional<z.ZodObject<{
             enabled: z.ZodOptional<z.ZodBoolean>;
             timeout: z.ZodOptional<z.ZodNumber>;
@@ -246,21 +299,77 @@ export declare const SDKConfigSchema: z.ZodObject<{
             enabled?: boolean | undefined;
             pollingInterval?: number | undefined;
         }>>;
-    }, z.ZodTypeAny, "passthrough"> | undefined;
-    logging?: {
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        gasFree: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodOptional<z.ZodBoolean>;
+            timeout: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            enabled?: boolean | undefined;
+            timeout?: number | undefined;
+        }, {
+            enabled?: boolean | undefined;
+            timeout?: number | undefined;
+        }>>;
+        watchTower: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodOptional<z.ZodBoolean>;
+            pollingInterval: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            enabled?: boolean | undefined;
+            pollingInterval?: number | undefined;
+        }, {
+            enabled?: boolean | undefined;
+            pollingInterval?: number | undefined;
+        }>>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        gasFree: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodOptional<z.ZodBoolean>;
+            timeout: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            enabled?: boolean | undefined;
+            timeout?: number | undefined;
+        }, {
+            enabled?: boolean | undefined;
+            timeout?: number | undefined;
+        }>>;
+        watchTower: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodOptional<z.ZodBoolean>;
+            pollingInterval: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            enabled?: boolean | undefined;
+            pollingInterval?: number | undefined;
+        }, {
+            enabled?: boolean | undefined;
+            pollingInterval?: number | undefined;
+        }>>;
+    }, z.ZodTypeAny, "passthrough">>>;
+    logging: z.ZodOptional<z.ZodObject<{
+        level: z.ZodOptional<z.ZodNativeEnum<typeof LogLevel>>;
+        logger: z.ZodOptional<z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
         level?: LogLevel | undefined;
         logger?: ((...args: unknown[]) => unknown) | undefined;
-    } | undefined;
-}>;
+    }, {
+        level?: LogLevel | undefined;
+        logger?: ((...args: unknown[]) => unknown) | undefined;
+    }>>;
+    options: z.ZodOptional<z.ZodObject<{
+        strictMode: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        strictMode?: boolean | undefined;
+    }, {
+        strictMode?: boolean | undefined;
+    }>>;
+}, z.ZodTypeAny, "passthrough">>;
 /**
  * SDK Configuration
  */
 export interface SDKConfig {
     /**
      * API key for Orbis services (Watch Tower, Gas-Free, etc.).
-     * Required for all backend services.
+     * Required when `features.gasFree.enabled` or `features.watchTower.enabled` is true.
+     * Omit for local RGB / wallet-only usage when those features are disabled.
      */
-    apiKey: string;
+    apiKey?: string;
     /**
      * SDK environment (testnet or mainnet).
      * Determines which network and service endpoints to use.

package/lib/typescript/src/types/SDKConfig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SDKConfig.d.ts","sourceRoot":"","sources":["../../../../src/types/SDKConfig.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"SDKConfig.d.ts","sourceRoot":"","sources":["../../../../src/types/SDKConfig.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orbis1-sdk-rn",
-  "version": "0.0.9",
+  "version": "0.2.0",
   "description": "Orbis1 SDK for React Native with RGB core, Watch Tower, and Gas-Free transfers.",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",
@@ -57,14 +57,14 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/orgs/Orbis-1/orbis1-sdk-rn.git"
+    "url": "git+https://github.com/Orbis-1/orbis1-sdk-rn.git"
   },
   "author": "Orbis1 <dev@orbis1.io> (https://github.com/orgs/Orbis-1)",
   "license": "MIT",
   "bugs": {
-    "url": "https://github.com/orgs/Orbis-1/orbis1-sdk-rn/issues"
+    "url": "https://github.com/Orbis-1/orbis1-sdk-rn/issues"
   },
-  "homepage": "https://github.com/orgs/Orbis-1/orbis1-sdk-rn#readme",
+  "homepage": "https://github.com/Orbis-1/orbis1-sdk-rn#readme",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
   },

package/src/Orbis1SDK.ts

@@ -69,6 +69,7 @@ export class Orbis1SDK {
           : BitcoinNetwork.TESTNET4;
 
       this.wallet = new Wallet(this.config.wallet.keys, {
+        dataDir: this.config.wallet.dataDir,
         network,
         supportedSchemas: this.config.wallet.supportedSchemas,
         maxAllocationsPerUtxo: this.config.wallet.maxAllocationsPerUtxo,
@@ -147,7 +148,7 @@ export class Orbis1SDK {
         name: Feature.GAS_FREE,
         enabled: true,
         environment: this.config.environment,
-        apiKey: this.config.apiKey,
+        apiKey: this.config.apiKey!,
         timeout: features.gasFree.timeout,
       });
       this.featureRegistry.register(Feature.GAS_FREE, gasFreeModule);
@@ -160,7 +161,7 @@ export class Orbis1SDK {
         name: Feature.WATCH_TOWER,
         enabled: true,
         environment: this.config.environment,
-        apiKey: this.config.apiKey,
+        apiKey: this.config.apiKey!,
       });
       this.featureRegistry.register(Feature.WATCH_TOWER, watchTowerModule);
       await watchTowerModule.initialize(this.wallet, this.logger); // Wallet parameter ignored by Watch Tower

package/src/core/NativeRgb.ts

@@ -31,6 +31,7 @@ export interface Spec extends TurboModule {
   }>;
   restoreBackup(path: string, password: string): Promise<void>;
   initializeWallet(
+    dataDir: string | null,
     network: string,
     accountXpubVanilla: string,
     accountXpubColored: string,

package/src/core/Wallet.ts

@@ -2,6 +2,7 @@ import Rgb from './NativeRgb';
 import * as Interfaces from './Interfaces';
 
 export interface WalletOptions {
+  dataDir?: string;
   network?: Interfaces.BitcoinNetwork;
   supportedSchemas?: Interfaces.AssetSchema[];
   maxAllocationsPerUtxo?: number;
@@ -11,6 +12,7 @@ export interface WalletOptions {
 export class Wallet {
   private walletId: number | null = null;
   private keys: Interfaces.Keys;
+  private dataDir?: string;
   private network: Interfaces.BitcoinNetwork;
   private supportedSchemas: Interfaces.AssetSchema[];
   private maxAllocationsPerUtxo: number;
@@ -21,6 +23,7 @@ export class Wallet {
    * Creates a new Wallet instance with the provided keys and configuration.
    * @param keys - The cryptographic keys required for wallet operations (mnemonic, master fingerprint, xPubs)
    * @param options - Optional wallet configuration settings
+   * @param options.dataDir - Absolute path to directory where wallet data will be stored (optional, defaults to app documents directory)
    * @param options.network - The Bitcoin network to use (defaults to 'TESTNET4')
    * @param options.supportedSchemas - List of RGB asset schemas the wallet supports (defaults to CFA, NIA, UDA)
    * @param options.maxAllocationsPerUtxo - Maximum number of RGB allocations allowed per UTXO (defaults to 1)
@@ -28,6 +31,7 @@ export class Wallet {
    */
   constructor(keys: Interfaces.Keys, options?: WalletOptions) {
     this.keys = keys;
+    this.dataDir = options?.dataDir;
     this.network = options?.network || Interfaces.BitcoinNetwork.TESTNET4;
     this.supportedSchemas = options?.supportedSchemas || [
       Interfaces.AssetSchema.CFA,
@@ -57,6 +61,7 @@ export class Wallet {
     // Start initialization
     this.initializationPromise = (async () => {
       this.walletId = await Rgb.initializeWallet(
+        this.dataDir || null,
         this.network,
         this.keys.accountXpubVanilla,
         this.keys.accountXpubColored,

package/src/features/gas-free/GasFreeModule.ts

@@ -261,7 +261,6 @@ export class GasFreeModule implements IFeatureModule<GasFreeConfig> {
       const submitResult = await this.submitPSBT(
         feeQuote.quoteId,
         psbtResult,
-        feeQuote.serviceFeeInvoice,
         request.assetId
       );
 
@@ -273,9 +272,7 @@ export class GasFreeModule implements IFeatureModule<GasFreeConfig> {
         submitResult.signedPsbtBase64
       );
 
-      // Step 4: Notify service of successful broadcast.
-      // The service uses txid to confirm the transaction landed in mempool
-      // and calls its own wallet.refresh() to claim the RGB service fee.
+      // Step 4: Notify service of successful broadcast
       await this.verifyTransfer(feeQuote.quoteId, txid, userSignedPsbt);
 
       // Mark as verified
@@ -341,6 +338,7 @@ export class GasFreeModule implements IFeatureModule<GasFreeConfig> {
       assetId: request.assetId,
       numInputs: request.numInputs || 1, // defaults to 1 inputs if not provided (1 user input)
       numOutputs: request.numOutputs || 2, // defaults to 2 outputs if not provided (1 OP_RETURN, 1 user change <equal val as input>)
+      recipientInvoice: request.recipientInvoice,
     });
 
     // Check quote expiration
@@ -439,14 +437,17 @@ export class GasFreeModule implements IFeatureModule<GasFreeConfig> {
       service: decodedServiceInvoice,
     });
 
+    const recipientIsWitness = feeQuote.witnessUtxoFundingSats > 0;
+
     // Build recipient map for sendBegin
-    // Note: Recipient requires assignment field with type and amount
+    // Note: Recipient requires assignment field with type and amount.
     // Important: Decoded invoices may have 'ANY' type (wildcard), but sendBegin
     // requires a concrete assignment type. Always use 'FUNGIBLE' for asset transfers.
     const recipientMap: Record<
       string,
       Array<{
         recipientId: string;
+        witnessData?: { amountSat: number; blinding?: number };
         assignment: { type: AssignmentType; amount: number };
         transportEndpoints: string[];
       }>
@@ -455,6 +456,12 @@ export class GasFreeModule implements IFeatureModule<GasFreeConfig> {
         {
           // Recipient 1: The actual transfer to the merchant / end recipient
           recipientId: decodedRecipientInvoice.recipientId,
+          ...(recipientIsWitness && {
+            witnessData: {
+              amountSat: feeQuote.witnessUtxoFundingSats,
+              blinding: 0, // Default blinding factor (rgb-lib requires this field)
+            },
+          }),
           assignment: {
             // Use FUNGIBLE type for asset transfers (invoice may have 'ANY' wildcard type)
             type: 'FUNGIBLE',
@@ -516,7 +523,6 @@ export class GasFreeModule implements IFeatureModule<GasFreeConfig> {
    *
    * @param quoteId - Quote ID from the fee quote
    * @param psbtResult - PSBT build result from buildPSBT()
-   * @param serviceFeeInvoice - Service fee RGB invoice from the quote
    * @param assetId - Asset ID being transferred
    * @returns Submit result with service-signed PSBT
    *
@@ -525,7 +531,6 @@ export class GasFreeModule implements IFeatureModule<GasFreeConfig> {
    * const submitResult = await gasFree.submitPSBT(
    *   quote.quoteId,
    *   psbtResult,
-   *   quote.serviceFeeInvoice,
    *   request.assetId
    * );
    * console.log('Service signed PSBT:', submitResult.signedPsbtBase64);
@@ -534,7 +539,6 @@ export class GasFreeModule implements IFeatureModule<GasFreeConfig> {
   async submitPSBT(
     quoteId: string,
     psbtResult: PSBTBuildResult,
-    serviceFeeInvoice: string,
     assetId: string
   ): Promise<PSBTSubmitResult> {
     this.logger?.debug('Step 3: Reading consignment and submitting to service');
@@ -548,7 +552,6 @@ export class GasFreeModule implements IFeatureModule<GasFreeConfig> {
       quoteId,
       psbtBase64: psbtResult.unsignedPsbt,
       consignmentBase64,
-      rgbInvoice: serviceFeeInvoice,
     });
 
     this.currentState.status = 'submitted';
@@ -620,7 +623,7 @@ export class GasFreeModule implements IFeatureModule<GasFreeConfig> {
    *
    * @param quoteId - Quote ID from the fee quote
    * @param txid - Transaction ID from broadcastTransfer()
-   * @param signedPsbtBase64 - Fully-signed PSBT from broadcastTransfer()
+   * @param signedPsbtBase64 - Base64-encoded signed PSBT
    * @returns Verification result from the service
    *
    * @example
@@ -628,7 +631,7 @@ export class GasFreeModule implements IFeatureModule<GasFreeConfig> {
    * const verifyResult = await gasFree.verifyTransfer(
    *   quote.quoteId,
    *   broadcastResult.txid,
-   *   broadcastResult.userSignedPsbt
+   *   signedPsbtBase64
    * );
    * console.log('Verification status:', verifyResult.status);
    * console.log('In mempool:', verifyResult.inMempool);
@@ -644,8 +647,8 @@ export class GasFreeModule implements IFeatureModule<GasFreeConfig> {
     const verifyResult = await this.serviceClient!.verifyTransfer({
       quoteId,
       transferSuccess: true,
-      signedPsbtBase64,
       txid,
+      signedPsbtBase64,
     });
 
     this.logger?.debug('Transfer verified', {

package/src/features/gas-free/client/ServiceClient.ts

@@ -197,12 +197,6 @@ export class ServiceClient implements IServiceClient {
       ]);
     }
 
-    if (!request.rgbInvoice || request.rgbInvoice.trim().length === 0) {
-      throw new InvalidPSBTError('RGB invoice is required', [
-        'rgbInvoice cannot be empty',
-      ]);
-    }
-
     // Make API request with retry
     try {
       return await retryWithBackoff(async () => {

package/src/features/gas-free/types/FeeQuote.ts

@@ -50,10 +50,12 @@ export interface FeeQuote {
   serviceFeeAmount: number;
   /** Asset type for service fee */
   assetType?: string;
+  /** Satoshi amount needed to fund witness UTXO (0 for blinded invoices, typically 1000 for witness invoices) */
+  witnessUtxoFundingSats: number;
   /** Mining UTXO provided by backend */
   miningUTXO: MiningUTXO;
-  /** Mining change UTXO details */
-  miningChangeUTXO: MiningChangeUTXO;
+  /** Mining change UTXO details (undefined if entire mining UTXO is consumed) */
+  miningChangeUTXO?: MiningChangeUTXO;
   /** RGB invoice for service fee payment */
   serviceFeeInvoice: string;
   /** Service fee recipient ID (utxob) */
@@ -78,6 +80,8 @@ export interface FeeQuoteRequest {
   numInputs: number;
   /** Number of USER's transaction outputs (INCLUDES OP_RETURN, must be >= 2) */
   numOutputs: number;
+  /** RGB invoice for the recipient (mandatory) */
+  recipientInvoice: string;
 }
 
 /**

package/src/features/gas-free/types/GasFreeRequest.ts

@@ -20,7 +20,7 @@ export interface GasFreeTransferRequest {
   /** Amount of RGB asset to send */
   amount: string;
 
-  /** Recipient RGB invoice (blinded UTXO) */
+  /** Recipient RGB invoice (blinded UTXO or witness output) */
   recipientInvoice: string;
 
   /** Transport endpoints for RGB transfer (e.g., ['rpc://...']) */

package/src/features/gas-free/types/GasFreeResult.ts

@@ -16,8 +16,6 @@ export interface SubmitPSBTRequest {
   psbtBase64: string;
   /** Base64-encoded RGB consignment file (.rgbc) */
   consignmentBase64: string;
-  /** RGB invoice string for service fee payment */
-  rgbInvoice: string;
 }
 
 /**

package/src/features/gas-free/utils/validation.ts

@@ -66,8 +66,12 @@ export const FeeQuoteSchema = z.object({
     .number()
     .nonnegative('Service fee amount must be non-negative'),
   assetType: z.string().optional(),
+  witnessUtxoFundingSats: z
+    .number()
+    .int()
+    .nonnegative('Witness UTXO funding sats must be non-negative'),
   miningUTXO: MiningUTXOSchema,
-  miningChangeUTXO: MiningChangeUTXOSchema,
+  miningChangeUTXO: MiningChangeUTXOSchema.optional(),
   serviceFeeInvoice: z.string().min(1, 'Service fee invoice must not be empty'),
   serviceFeeRecipientId: z
     .string()
@@ -88,16 +92,21 @@ export const FeeQuoteRequestSchema = z.object({
     .number()
     .int()
     .min(2, 'Number of outputs must be at least 2 (includes OP_RETURN)'),
+  recipientInvoice: z
+    .string()
+    .min(1, 'Recipient invoice cannot be empty')
+    .regex(/^rgb1?:/, 'Recipient invoice must start with rgb: or rgb1:'),
 }) satisfies z.ZodType<FeeQuoteRequest>;
 
 /**
  * Schema for Submit PSBT Request
  */
 export const SubmitPSBTRequestSchema = z.object({
-  quoteId: z.string().min(1, 'Quote ID must not be empty'),
-  psbtBase64: z.string().min(1, 'PSBT base64 must not be empty'),
-  consignmentBase64: z.string().min(1, 'Consignment base64 must not be empty'),
-  rgbInvoice: z.string().min(1, 'RGB invoice must not be empty'),
+  quoteId: z.string().uuid('Quote ID must be a valid UUID'),
+  psbtBase64: z.string().min(1, 'PSBT cannot be empty'),
+  consignmentBase64: z
+    .string()
+    .min(1, 'Consignment data is required (base64-encoded)'),
 }) satisfies z.ZodType<SubmitPSBTRequest>;
 
 /**

package/src/types/SDKConfig.ts

@@ -17,6 +17,8 @@ export interface WalletConfig {
   enabled: boolean;
   /** Wallet keys (mnemonic, xpubs, etc.) */
   keys: Keys;
+  /** Absolute path to directory where wallet data will be stored. If not provided, defaults to app documents directory. */
+  dataDir?: string;
   /** Supported asset schemas */
   supportedSchemas?: AssetSchema[];
   /** Maximum allocations per UTXO */
@@ -93,20 +95,26 @@ export const SDKOptionsSchema = z.object({
 
 /**
  * Zod schema for SDK configuration
+ *
+ * Note: `apiKey` is intentionally omitted here — it is validated manually in
+ * `validateSDKConfig` so it can be optional when Gas-Free / Watch Tower are off.
+ * Including it in Zod led to stale builds or edge cases surfacing as
+ * "apiKey: API key is required".
  */
-export const SDKConfigSchema = z.object({
-  apiKey: z.string().min(1, 'API key is required'),
-  environment: z.nativeEnum(Environment).default(Environment.MAINNET),
-  features: z
-    .object({
-      gasFree: GasFreeFeatureConfigSchema.optional(),
-      watchTower: WatchTowerFeatureConfigSchema.optional(),
-    })
-    .passthrough()
-    .optional(),
-  logging: LoggingConfigSchema.optional(),
-  options: SDKOptionsSchema.optional(),
-});
+export const SDKConfigSchema = z
+  .object({
+    environment: z.nativeEnum(Environment).default(Environment.MAINNET),
+    features: z
+      .object({
+        gasFree: GasFreeFeatureConfigSchema.optional(),
+        watchTower: WatchTowerFeatureConfigSchema.optional(),
+      })
+      .passthrough()
+      .optional(),
+    logging: LoggingConfigSchema.optional(),
+    options: SDKOptionsSchema.optional(),
+  })
+  .passthrough();
 
 /**
  * SDK Configuration
@@ -114,9 +122,10 @@ export const SDKConfigSchema = z.object({
 export interface SDKConfig {
   /**
    * API key for Orbis services (Watch Tower, Gas-Free, etc.).
-   * Required for all backend services.
+   * Required when `features.gasFree.enabled` or `features.watchTower.enabled` is true.
+   * Omit for local RGB / wallet-only usage when those features are disabled.
    */
-  apiKey: string;
+  apiKey?: string;
 
   /**
    * SDK environment (testnet or mainnet).
@@ -207,15 +216,38 @@ export function validateSDKConfig(config: SDKConfig): void {
         const path = err.path.join('.');
         return path ? `${path}: ${err.message}` : err.message;
       });
-      throw new Error(
-        `Configuration validation failed:\n  - ${messages.join('\n  - ')}`
-      );
+      // No outer "Configuration validation failed" prefix — Orbis1SDK wraps once
+      throw new Error(messages.join('\n  - '));
     }
     throw error;
   }
 
-  // Validate API key prefix matches environment
-  const apiKey = config.apiKey;
+  if (
+    config.apiKey !== undefined &&
+    config.apiKey !== null &&
+    typeof config.apiKey !== 'string'
+  ) {
+    throw new Error('apiKey must be a string when provided');
+  }
+
+  const needsApiKey =
+    config.features?.gasFree?.enabled === true ||
+    config.features?.watchTower?.enabled === true;
+
+  const apiKeyTrimmed =
+    typeof config.apiKey === 'string' ? config.apiKey.trim() : '';
+  const apiKey = apiKeyTrimmed.length > 0 ? apiKeyTrimmed : undefined;
+
+  if (needsApiKey && !apiKey) {
+    throw new Error(
+      'API key is required when Gas-Free or Watch Tower is enabled'
+    );
+  }
+
+  if (!apiKey) {
+    return;
+  }
+
   const environment = config.environment ?? Environment.MAINNET;
 
   if (
@@ -249,8 +281,14 @@ export function validateSDKConfig(config: SDKConfig): void {
  * @returns Merged configuration with defaults
  */
 export function mergeWithDefaults(config: SDKConfig): SDKConfig {
+  const apiKeyNormalized =
+    typeof config.apiKey === 'string'
+      ? config.apiKey.trim() || undefined
+      : config.apiKey;
+
   return {
     ...config,
+    apiKey: apiKeyNormalized,
     environment: config.environment ?? Environment.MAINNET,
     features: {
       ...DEFAULT_SDK_CONFIG.features,