@caatinga/client 0.2.2 → 0.2.4

package/README.md

@@ -19,6 +19,16 @@ import { freighterWalletAdapter } from "@caatinga/client/freighter";
 
 The `@caatinga/client/freighter` subpath is optional and only needed when you want the bundled Freighter adapter.
 
+For multi-wallet support, add Stellar Wallets Kit:
+
+```bash
+pnpm add github:Creit-Tech/Stellar-Wallets-Kit#v0.0.7
+```
+
+```ts
+import { createStellarWalletsKitAdapter } from "@caatinga/client/stellar-wallets-kit";
+```
+
 ## What It Solves
 
 `@caatinga/client` is the supported browser and Node integration layer for invoking generated Soroban bindings with Caatinga artifacts, network configuration, and a wallet adapter.
@@ -49,16 +59,21 @@ Supported type-only root exports:
 - `CaatingaInvokeResult`
 - `CaatingaInvokeStatus`
 - `CaatingaNetwork`
+- `CaatingaReadOptions`
+- `CaatingaReadResult`
 - `CaatingaWalletAdapter`
 - `CaatingaXdrBuildResult`
 
 Supported subpath export:
 
 - `@caatinga/client/freighter` -> `freighterWalletAdapter` (optional)
+- `@caatinga/client/stellar-wallets-kit` -> `createStellarWalletsKitAdapter` (optional)
 
 Primary flow:
 
 - `createCaatingaClient(...)`
+- `client.contract(name).read(method, args?)`
+- `client.contract(name).simulate(method, args?)`
 - `client.contract(name).invoke(method, args?)`
 - `client.contract(name).buildXdr(method, args?)`
 
@@ -66,10 +81,12 @@ Primary flow:
 
 ```ts
 import { createCaatingaClient } from "@caatinga/client";
-import { freighterWalletAdapter } from "@caatinga/client/freighter";
+import { createStellarWalletsKitAdapter } from "@caatinga/client/stellar-wallets-kit";
 import * as Counter from "./contracts/generated/counter";
 import artifacts from "../caatinga.artifacts.json";
 
+const wallet = createStellarWalletsKitAdapter();
+
 const client = createCaatingaClient({
   network: {
     name: "testnet",
@@ -77,7 +94,7 @@ const client = createCaatingaClient({
     networkPassphrase: "Test SDF Network ; September 2015"
   },
   artifacts,
-  wallet: freighterWalletAdapter,
+  wallet,
   contracts: {
     counter: {
       binding: Counter
@@ -85,7 +102,9 @@ const client = createCaatingaClient({
   }
 });
 
-const result = await client.contract("counter").invoke("increment");
+const before = await client.contract("counter").read<number>("get");
+const increment = await client.contract("counter").invoke<number>("increment");
+const after = increment.result ?? await client.contract("counter").read<number>("get");
 ```
 
 ## Wallet Adapter Contract

package/dist/freighter.d.cts

@@ -1,4 +1,4 @@
-import { C as CaatingaWalletAdapter } from './types-DUgMJXLA.cjs';
+import { C as CaatingaWalletAdapter } from './types-D4XEyX4J.cjs';
 import '@caatinga/core/browser';
 
 declare const freighterWalletAdapter: CaatingaWalletAdapter;

package/dist/freighter.d.ts

@@ -1,4 +1,4 @@
-import { C as CaatingaWalletAdapter } from './types-DUgMJXLA.js';
+import { C as CaatingaWalletAdapter } from './types-D4XEyX4J.js';
 import '@caatinga/core/browser';
 
 declare const freighterWalletAdapter: CaatingaWalletAdapter;

package/dist/index.cjs

@@ -180,40 +180,50 @@ var CaatingaContractClient = class {
       debug: debugRaw
     });
     let signedXdr;
-    try {
-      signedXdr = await this.withWalletTimeout(
-        "signTransaction",
-        () => this.config.wallet.signTransaction({
-          xdr: xdr.preparedXdr,
-          networkPassphrase: this.config.network.networkPassphrase
-        })
-      );
-    } catch (error) {
-      if (error instanceof import_browser4.CaatingaError) {
-        throw error;
+    const signTransaction = async (xdr2) => {
+      try {
+        signedXdr = await this.withWalletTimeout(
+          "signTransaction",
+          () => this.config.wallet.signTransaction({
+            xdr: xdr2,
+            networkPassphrase: this.config.network.networkPassphrase
+          })
+        );
+      } catch (error) {
+        if (error instanceof import_browser4.CaatingaError) {
+          throw error;
+        }
+        throw new import_browser4.CaatingaError(
+          `Failed to sign XDR for "${this.contractName}.${method}".`,
+          import_browser4.CaatingaErrorCode.XDR_SIGN_FAILED,
+          "Connect a wallet and approve the transaction.",
+          error
+        );
       }
-      throw new import_browser4.CaatingaError(
-        `Failed to sign XDR for "${this.contractName}.${method}".`,
-        import_browser4.CaatingaErrorCode.XDR_SIGN_FAILED,
-        "Connect a wallet and approve the transaction.",
-        error
-      );
-    }
-    if (typeof signedXdr !== "string" || signedXdr.trim().length === 0) {
-      throw new import_browser4.CaatingaError(
-        `Failed to sign XDR for "${this.contractName}.${method}".`,
-        import_browser4.CaatingaErrorCode.XDR_SIGN_FAILED,
-        "Wallet returned an empty or invalid signed XDR. The user may have dismissed the signing prompt.",
-        signedXdr
-      );
-    }
+      if (typeof signedXdr !== "string" || signedXdr.trim().length === 0) {
+        throw new import_browser4.CaatingaError(
+          `Failed to sign XDR for "${this.contractName}.${method}".`,
+          import_browser4.CaatingaErrorCode.XDR_SIGN_FAILED,
+          "Wallet returned an empty or invalid signed XDR. The user may have dismissed the signing prompt.",
+          signedXdr
+        );
+      }
+      return { signedTxXdr: signedXdr };
+    };
     const raw = await submitTransaction(
       transaction,
-      signedXdr,
+      signTransaction,
       this.contractName,
       method,
       this.config.network.rpcUrl
     );
+    if (typeof transaction.signAndSend === "function" && signedXdr === void 0) {
+      throw new import_browser4.CaatingaError(
+        `Failed to sign XDR for "${this.contractName}.${method}".`,
+        import_browser4.CaatingaErrorCode.XDR_SIGN_FAILED,
+        "Wallet returned an empty or invalid signed XDR. The generated transaction did not request a wallet signature."
+      );
+    }
     const normalized = normalizeSubmitResult(raw);
     return {
       status: "confirmed",
@@ -226,12 +236,35 @@ var CaatingaContractClient = class {
         xdr: {
           unsigned: xdr.unsignedXdr,
           prepared: xdr.preparedXdr,
-          signed: signedXdr
+          ...signedXdr ? { signed: signedXdr } : {}
         }
       } : {},
       ...debugRaw ? { raw } : {}
     };
   }
+  async simulate(method, argsOrOptions, maybeOptions) {
+    const { args, debugRaw } = splitReadArgsAndOptions(argsOrOptions, maybeOptions);
+    const { contractId, transaction } = await this.createTransaction(method, args);
+    const raw = await prepareReadTransaction(
+      transaction,
+      this.contractName,
+      method,
+      this.config.network.rpcUrl
+    );
+    const result = readSimulationResult(raw, this.contractName, method);
+    return {
+      status: "simulated",
+      contract: this.contractName,
+      method,
+      contractId,
+      result,
+      ...debugRaw ? { raw } : {}
+    };
+  }
+  async read(method, argsOrOptions, maybeOptions) {
+    const result = await this.simulate(method, argsOrOptions, maybeOptions);
+    return result.result;
+  }
   async createTransaction(method, args) {
     const contractId = resolveContractId({
       artifacts: this.config.artifacts,
@@ -323,38 +356,100 @@ function splitInvokeArgsAndOptions(argsOrOptions, maybeOptions) {
     debugRaw: maybeOptions?.debugRaw ?? false
   };
 }
-async function submitTransaction(transaction, signedXdr, contractName, method, rpcUrl) {
+function splitReadArgsAndOptions(argsOrOptions, maybeOptions) {
+  const looksLikeOptions = argsOrOptions !== void 0 && "debugRaw" in argsOrOptions && maybeOptions === void 0;
+  if (looksLikeOptions) {
+    const options = argsOrOptions;
+    return {
+      args: void 0,
+      debugRaw: options.debugRaw ?? false
+    };
+  }
+  return {
+    args: argsOrOptions,
+    debugRaw: maybeOptions?.debugRaw ?? false
+  };
+}
+async function submitTransaction(transaction, signTransaction, contractName, method, rpcUrl) {
   const candidate = transaction;
-  const submit = candidate.signAndSend ?? candidate.send;
-  if (typeof submit !== "function") {
-    throw new import_browser4.CaatingaError(
-      `Binding transaction for "${contractName}.${method}" cannot be submitted.`,
-      import_browser4.CaatingaErrorCode.XDR_SUBMIT_FAILED,
-      "Regenerate bindings or provide a compatible binding adapter."
-    );
+  if (typeof candidate.signAndSend === "function") {
+    try {
+      const raw = await candidate.signAndSend.call(transaction, { signTransaction });
+      assertSubmitResultRecognized(raw, contractName, method);
+      return raw;
+    } catch (error) {
+      if (error instanceof import_browser4.CaatingaError) {
+        throw error;
+      }
+      throw new import_browser4.CaatingaError(
+        `Failed to submit XDR for "${contractName}.${method}".`,
+        import_browser4.CaatingaErrorCode.XDR_SUBMIT_FAILED,
+        `RPC: ${rpcUrl}. Check wallet signature and RPC connectivity.`,
+        error
+      );
+    }
+  }
+  if (typeof candidate.send === "function") {
+    try {
+      const raw = await candidate.send.call(transaction);
+      assertSubmitResultRecognized(raw, contractName, method);
+      return raw;
+    } catch (error) {
+      if (error instanceof import_browser4.CaatingaError) {
+        throw error;
+      }
+      throw new import_browser4.CaatingaError(
+        `Failed to submit XDR for "${contractName}.${method}".`,
+        import_browser4.CaatingaErrorCode.XDR_SUBMIT_FAILED,
+        `RPC: ${rpcUrl}. Check wallet signature and RPC connectivity.`,
+        error
+      );
+    }
+  }
+  throw new import_browser4.CaatingaError(
+    `Binding transaction for "${contractName}.${method}" cannot be submitted.`,
+    import_browser4.CaatingaErrorCode.XDR_SUBMIT_FAILED,
+    "Regenerate bindings or provide a compatible binding adapter."
+  );
+}
+async function prepareReadTransaction(transaction, contractName, method, rpcUrl) {
+  const candidate = transaction;
+  if (typeof candidate.prepare !== "function") {
+    return transaction;
   }
   try {
-    const raw = await submit.call(transaction, { signedXdr });
-    assertSubmitResultRecognized(raw, contractName, method);
-    return raw;
+    return await candidate.prepare.call(transaction);
   } catch (error) {
     if (error instanceof import_browser4.CaatingaError) {
       throw error;
     }
     throw new import_browser4.CaatingaError(
-      `Failed to submit XDR for "${contractName}.${method}".`,
-      import_browser4.CaatingaErrorCode.XDR_SUBMIT_FAILED,
-      `RPC: ${rpcUrl}. Check wallet signature and RPC connectivity.`,
+      `Failed to prepare XDR for "${contractName}.${method}".`,
+      import_browser4.CaatingaErrorCode.XDR_PREPARE_FAILED,
+      `RPC: ${rpcUrl}. Check connectivity, simulation errors, and binding compatibility.`,
       error
     );
   }
 }
+function readSimulationResult(raw, contractName, method) {
+  if (raw !== null && typeof raw === "object" && "result" in raw) {
+    const result = raw.result;
+    if (result !== void 0) {
+      return result;
+    }
+  }
+  throw new import_browser4.CaatingaError(
+    `Simulation for "${contractName}.${method}" did not return a result.`,
+    import_browser4.CaatingaErrorCode.READ_RESULT_MISSING,
+    `Expected "${contractName}.${method}" to expose a simulation result. Use debugRaw to inspect the generated binding output.`
+  );
+}
 function assertSubmitResultRecognized(raw, contractName, method) {
   if (raw === null || typeof raw !== "object") {
     return;
   }
   const record = raw;
-  const hasTransactionId = "txHash" in record || "transactionHash" in record || "hash" in record;
+  const hasTransactionId = "txHash" in record || "transactionHash" in record || "hash" in record || hasNestedSendTransactionResponseHash(record);
   const hasResult = "result" in record;
   if (hasTransactionId || hasResult) {
     return;
@@ -362,13 +457,17 @@ function assertSubmitResultRecognized(raw, contractName, method) {
   throw new import_browser4.CaatingaError(
     `Submit returned an unrecognized payload for "${contractName}.${method}".`,
     import_browser4.CaatingaErrorCode.XDR_RESULT_FAILED,
-    "Expected txHash, transactionHash, hash, or result on the submit response. Use debugRaw to inspect the binding output."
+    "Expected txHash, transactionHash, hash, sendTransactionResponse.hash, or result on the submit response. Use debugRaw to inspect the binding output."
   );
 }
+function hasNestedSendTransactionResponseHash(record) {
+  const response = record.sendTransactionResponse;
+  return response !== null && typeof response === "object" && "hash" in response;
+}
 function normalizeSubmitResult(raw) {
   const candidate = raw;
   return {
-    transactionHash: candidate.txHash ?? candidate.transactionHash ?? candidate.hash,
+    transactionHash: candidate.txHash ?? candidate.transactionHash ?? candidate.hash ?? candidate.sendTransactionResponse?.hash,
     result: candidate.result
   };
 }

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { a as CaatingaBindingAdapter, b as CaatingaClientConfig, c as CaatingaContractRegistration, d as CaatingaXdrBuildResult, e as CaatingaInvokeOptions, f as CaatingaInvokeResult } from './types-DUgMJXLA.cjs';
-export { g as CaatingaInvokeStatus, h as CaatingaNetwork, C as CaatingaWalletAdapter } from './types-DUgMJXLA.cjs';
+import { a as CaatingaBindingAdapter, b as CaatingaClientConfig, c as CaatingaContractRegistration, d as CaatingaXdrBuildResult, e as CaatingaInvokeOptions, f as CaatingaInvokeResult, g as CaatingaReadOptions, h as CaatingaReadResult } from './types-D4XEyX4J.cjs';
+export { i as CaatingaInvokeStatus, j as CaatingaNetwork, C as CaatingaWalletAdapter } from './types-D4XEyX4J.cjs';
 import { CaatingaArtifacts } from '@caatinga/core/browser';
 
 declare function resolveContractId(input: {
@@ -29,6 +29,8 @@ declare class CaatingaContractClient {
         debugRaw?: boolean;
     }): Promise<CaatingaXdrBuildResult>;
     invoke<T = unknown>(method: string, argsOrOptions?: Record<string, unknown> | CaatingaInvokeOptions, maybeOptions?: CaatingaInvokeOptions): Promise<CaatingaInvokeResult<T>>;
+    simulate<T = unknown>(method: string, argsOrOptions?: Record<string, unknown> | CaatingaReadOptions, maybeOptions?: CaatingaReadOptions): Promise<CaatingaReadResult<T>>;
+    read<T = unknown>(method: string, argsOrOptions?: Record<string, unknown> | CaatingaReadOptions, maybeOptions?: CaatingaReadOptions): Promise<T>;
     private createTransaction;
     private withWalletTimeout;
 }
@@ -46,4 +48,4 @@ declare function buildXdr(input: {
     debug?: boolean;
 }): Promise<CaatingaXdrBuildResult>;
 
-export { CaatingaBindingAdapter, CaatingaClientConfig, CaatingaContractClient, CaatingaContractRegistration, CaatingaInvokeOptions, CaatingaInvokeResult, CaatingaXdrBuildResult, buildXdr, createCaatingaClient, createDefaultBindingAdapter, resolveContractId };
+export { CaatingaBindingAdapter, CaatingaClientConfig, CaatingaContractClient, CaatingaContractRegistration, CaatingaInvokeOptions, CaatingaInvokeResult, CaatingaReadOptions, CaatingaReadResult, CaatingaXdrBuildResult, buildXdr, createCaatingaClient, createDefaultBindingAdapter, resolveContractId };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { a as CaatingaBindingAdapter, b as CaatingaClientConfig, c as CaatingaContractRegistration, d as CaatingaXdrBuildResult, e as CaatingaInvokeOptions, f as CaatingaInvokeResult } from './types-DUgMJXLA.js';
-export { g as CaatingaInvokeStatus, h as CaatingaNetwork, C as CaatingaWalletAdapter } from './types-DUgMJXLA.js';
+import { a as CaatingaBindingAdapter, b as CaatingaClientConfig, c as CaatingaContractRegistration, d as CaatingaXdrBuildResult, e as CaatingaInvokeOptions, f as CaatingaInvokeResult, g as CaatingaReadOptions, h as CaatingaReadResult } from './types-D4XEyX4J.js';
+export { i as CaatingaInvokeStatus, j as CaatingaNetwork, C as CaatingaWalletAdapter } from './types-D4XEyX4J.js';
 import { CaatingaArtifacts } from '@caatinga/core/browser';
 
 declare function resolveContractId(input: {
@@ -29,6 +29,8 @@ declare class CaatingaContractClient {
         debugRaw?: boolean;
     }): Promise<CaatingaXdrBuildResult>;
     invoke<T = unknown>(method: string, argsOrOptions?: Record<string, unknown> | CaatingaInvokeOptions, maybeOptions?: CaatingaInvokeOptions): Promise<CaatingaInvokeResult<T>>;
+    simulate<T = unknown>(method: string, argsOrOptions?: Record<string, unknown> | CaatingaReadOptions, maybeOptions?: CaatingaReadOptions): Promise<CaatingaReadResult<T>>;
+    read<T = unknown>(method: string, argsOrOptions?: Record<string, unknown> | CaatingaReadOptions, maybeOptions?: CaatingaReadOptions): Promise<T>;
     private createTransaction;
     private withWalletTimeout;
 }
@@ -46,4 +48,4 @@ declare function buildXdr(input: {
     debug?: boolean;
 }): Promise<CaatingaXdrBuildResult>;
 
-export { CaatingaBindingAdapter, CaatingaClientConfig, CaatingaContractClient, CaatingaContractRegistration, CaatingaInvokeOptions, CaatingaInvokeResult, CaatingaXdrBuildResult, buildXdr, createCaatingaClient, createDefaultBindingAdapter, resolveContractId };
+export { CaatingaBindingAdapter, CaatingaClientConfig, CaatingaContractClient, CaatingaContractRegistration, CaatingaInvokeOptions, CaatingaInvokeResult, CaatingaReadOptions, CaatingaReadResult, CaatingaXdrBuildResult, buildXdr, createCaatingaClient, createDefaultBindingAdapter, resolveContractId };

package/dist/index.js

@@ -150,40 +150,50 @@ var CaatingaContractClient = class {
       debug: debugRaw
     });
     let signedXdr;
-    try {
-      signedXdr = await this.withWalletTimeout(
-        "signTransaction",
-        () => this.config.wallet.signTransaction({
-          xdr: xdr.preparedXdr,
-          networkPassphrase: this.config.network.networkPassphrase
-        })
-      );
-    } catch (error) {
-      if (error instanceof CaatingaError4) {
-        throw error;
+    const signTransaction = async (xdr2) => {
+      try {
+        signedXdr = await this.withWalletTimeout(
+          "signTransaction",
+          () => this.config.wallet.signTransaction({
+            xdr: xdr2,
+            networkPassphrase: this.config.network.networkPassphrase
+          })
+        );
+      } catch (error) {
+        if (error instanceof CaatingaError4) {
+          throw error;
+        }
+        throw new CaatingaError4(
+          `Failed to sign XDR for "${this.contractName}.${method}".`,
+          CaatingaErrorCode4.XDR_SIGN_FAILED,
+          "Connect a wallet and approve the transaction.",
+          error
+        );
       }
-      throw new CaatingaError4(
-        `Failed to sign XDR for "${this.contractName}.${method}".`,
-        CaatingaErrorCode4.XDR_SIGN_FAILED,
-        "Connect a wallet and approve the transaction.",
-        error
-      );
-    }
-    if (typeof signedXdr !== "string" || signedXdr.trim().length === 0) {
-      throw new CaatingaError4(
-        `Failed to sign XDR for "${this.contractName}.${method}".`,
-        CaatingaErrorCode4.XDR_SIGN_FAILED,
-        "Wallet returned an empty or invalid signed XDR. The user may have dismissed the signing prompt.",
-        signedXdr
-      );
-    }
+      if (typeof signedXdr !== "string" || signedXdr.trim().length === 0) {
+        throw new CaatingaError4(
+          `Failed to sign XDR for "${this.contractName}.${method}".`,
+          CaatingaErrorCode4.XDR_SIGN_FAILED,
+          "Wallet returned an empty or invalid signed XDR. The user may have dismissed the signing prompt.",
+          signedXdr
+        );
+      }
+      return { signedTxXdr: signedXdr };
+    };
     const raw = await submitTransaction(
       transaction,
-      signedXdr,
+      signTransaction,
       this.contractName,
       method,
       this.config.network.rpcUrl
     );
+    if (typeof transaction.signAndSend === "function" && signedXdr === void 0) {
+      throw new CaatingaError4(
+        `Failed to sign XDR for "${this.contractName}.${method}".`,
+        CaatingaErrorCode4.XDR_SIGN_FAILED,
+        "Wallet returned an empty or invalid signed XDR. The generated transaction did not request a wallet signature."
+      );
+    }
     const normalized = normalizeSubmitResult(raw);
     return {
       status: "confirmed",
@@ -196,12 +206,35 @@ var CaatingaContractClient = class {
         xdr: {
           unsigned: xdr.unsignedXdr,
           prepared: xdr.preparedXdr,
-          signed: signedXdr
+          ...signedXdr ? { signed: signedXdr } : {}
         }
       } : {},
       ...debugRaw ? { raw } : {}
     };
   }
+  async simulate(method, argsOrOptions, maybeOptions) {
+    const { args, debugRaw } = splitReadArgsAndOptions(argsOrOptions, maybeOptions);
+    const { contractId, transaction } = await this.createTransaction(method, args);
+    const raw = await prepareReadTransaction(
+      transaction,
+      this.contractName,
+      method,
+      this.config.network.rpcUrl
+    );
+    const result = readSimulationResult(raw, this.contractName, method);
+    return {
+      status: "simulated",
+      contract: this.contractName,
+      method,
+      contractId,
+      result,
+      ...debugRaw ? { raw } : {}
+    };
+  }
+  async read(method, argsOrOptions, maybeOptions) {
+    const result = await this.simulate(method, argsOrOptions, maybeOptions);
+    return result.result;
+  }
   async createTransaction(method, args) {
     const contractId = resolveContractId({
       artifacts: this.config.artifacts,
@@ -293,38 +326,100 @@ function splitInvokeArgsAndOptions(argsOrOptions, maybeOptions) {
     debugRaw: maybeOptions?.debugRaw ?? false
   };
 }
-async function submitTransaction(transaction, signedXdr, contractName, method, rpcUrl) {
+function splitReadArgsAndOptions(argsOrOptions, maybeOptions) {
+  const looksLikeOptions = argsOrOptions !== void 0 && "debugRaw" in argsOrOptions && maybeOptions === void 0;
+  if (looksLikeOptions) {
+    const options = argsOrOptions;
+    return {
+      args: void 0,
+      debugRaw: options.debugRaw ?? false
+    };
+  }
+  return {
+    args: argsOrOptions,
+    debugRaw: maybeOptions?.debugRaw ?? false
+  };
+}
+async function submitTransaction(transaction, signTransaction, contractName, method, rpcUrl) {
   const candidate = transaction;
-  const submit = candidate.signAndSend ?? candidate.send;
-  if (typeof submit !== "function") {
-    throw new CaatingaError4(
-      `Binding transaction for "${contractName}.${method}" cannot be submitted.`,
-      CaatingaErrorCode4.XDR_SUBMIT_FAILED,
-      "Regenerate bindings or provide a compatible binding adapter."
-    );
+  if (typeof candidate.signAndSend === "function") {
+    try {
+      const raw = await candidate.signAndSend.call(transaction, { signTransaction });
+      assertSubmitResultRecognized(raw, contractName, method);
+      return raw;
+    } catch (error) {
+      if (error instanceof CaatingaError4) {
+        throw error;
+      }
+      throw new CaatingaError4(
+        `Failed to submit XDR for "${contractName}.${method}".`,
+        CaatingaErrorCode4.XDR_SUBMIT_FAILED,
+        `RPC: ${rpcUrl}. Check wallet signature and RPC connectivity.`,
+        error
+      );
+    }
+  }
+  if (typeof candidate.send === "function") {
+    try {
+      const raw = await candidate.send.call(transaction);
+      assertSubmitResultRecognized(raw, contractName, method);
+      return raw;
+    } catch (error) {
+      if (error instanceof CaatingaError4) {
+        throw error;
+      }
+      throw new CaatingaError4(
+        `Failed to submit XDR for "${contractName}.${method}".`,
+        CaatingaErrorCode4.XDR_SUBMIT_FAILED,
+        `RPC: ${rpcUrl}. Check wallet signature and RPC connectivity.`,
+        error
+      );
+    }
+  }
+  throw new CaatingaError4(
+    `Binding transaction for "${contractName}.${method}" cannot be submitted.`,
+    CaatingaErrorCode4.XDR_SUBMIT_FAILED,
+    "Regenerate bindings or provide a compatible binding adapter."
+  );
+}
+async function prepareReadTransaction(transaction, contractName, method, rpcUrl) {
+  const candidate = transaction;
+  if (typeof candidate.prepare !== "function") {
+    return transaction;
   }
   try {
-    const raw = await submit.call(transaction, { signedXdr });
-    assertSubmitResultRecognized(raw, contractName, method);
-    return raw;
+    return await candidate.prepare.call(transaction);
   } catch (error) {
     if (error instanceof CaatingaError4) {
       throw error;
     }
     throw new CaatingaError4(
-      `Failed to submit XDR for "${contractName}.${method}".`,
-      CaatingaErrorCode4.XDR_SUBMIT_FAILED,
-      `RPC: ${rpcUrl}. Check wallet signature and RPC connectivity.`,
+      `Failed to prepare XDR for "${contractName}.${method}".`,
+      CaatingaErrorCode4.XDR_PREPARE_FAILED,
+      `RPC: ${rpcUrl}. Check connectivity, simulation errors, and binding compatibility.`,
       error
     );
   }
 }
+function readSimulationResult(raw, contractName, method) {
+  if (raw !== null && typeof raw === "object" && "result" in raw) {
+    const result = raw.result;
+    if (result !== void 0) {
+      return result;
+    }
+  }
+  throw new CaatingaError4(
+    `Simulation for "${contractName}.${method}" did not return a result.`,
+    CaatingaErrorCode4.READ_RESULT_MISSING,
+    `Expected "${contractName}.${method}" to expose a simulation result. Use debugRaw to inspect the generated binding output.`
+  );
+}
 function assertSubmitResultRecognized(raw, contractName, method) {
   if (raw === null || typeof raw !== "object") {
     return;
   }
   const record = raw;
-  const hasTransactionId = "txHash" in record || "transactionHash" in record || "hash" in record;
+  const hasTransactionId = "txHash" in record || "transactionHash" in record || "hash" in record || hasNestedSendTransactionResponseHash(record);
   const hasResult = "result" in record;
   if (hasTransactionId || hasResult) {
     return;
@@ -332,13 +427,17 @@ function assertSubmitResultRecognized(raw, contractName, method) {
   throw new CaatingaError4(
     `Submit returned an unrecognized payload for "${contractName}.${method}".`,
     CaatingaErrorCode4.XDR_RESULT_FAILED,
-    "Expected txHash, transactionHash, hash, or result on the submit response. Use debugRaw to inspect the binding output."
+    "Expected txHash, transactionHash, hash, sendTransactionResponse.hash, or result on the submit response. Use debugRaw to inspect the binding output."
   );
 }
+function hasNestedSendTransactionResponseHash(record) {
+  const response = record.sendTransactionResponse;
+  return response !== null && typeof response === "object" && "hash" in response;
+}
 function normalizeSubmitResult(raw) {
   const candidate = raw;
   return {
-    transactionHash: candidate.txHash ?? candidate.transactionHash ?? candidate.hash,
+    transactionHash: candidate.txHash ?? candidate.transactionHash ?? candidate.hash ?? candidate.sendTransactionResponse?.hash,
     result: candidate.result
   };
 }

package/dist/stellar-wallets-kit.cjs

@@ -0,0 +1,109 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/stellar-wallets-kit.ts
+var stellar_wallets_kit_exports = {};
+__export(stellar_wallets_kit_exports, {
+  createStellarWalletsKitAdapter: () => createStellarWalletsKitAdapter
+});
+module.exports = __toCommonJS(stellar_wallets_kit_exports);
+
+// src/adapters/stellar-wallets-kit.ts
+var import_stellar_wallets_kit = require("stellar-wallets-kit");
+function createStellarWalletsKitAdapter(options = {}) {
+  const kit = options.kit ?? new import_stellar_wallets_kit.StellarWalletsKit({
+    network: options.network ?? import_stellar_wallets_kit.WalletNetwork.TESTNET,
+    selectedWallet: options.selectedWallet ?? import_stellar_wallets_kit.WalletType.XBULL
+  });
+  let publicKey;
+  let isWalletConnectStarted = false;
+  const sessionDeletedCallbacks = /* @__PURE__ */ new Set();
+  return {
+    kit,
+    async setWallet(wallet) {
+      await kit.setWallet(wallet);
+      publicKey = void 0;
+    },
+    async setNetwork(network) {
+      await kit.setNetwork(network);
+      publicKey = void 0;
+    },
+    async getPublicKey() {
+      publicKey = await kit.getPublicKey();
+      return publicKey;
+    },
+    async signTransaction({ xdr, networkPassphrase }) {
+      const walletNetwork = resolveWalletNetwork(networkPassphrase);
+      if (walletNetwork) {
+        await kit.setNetwork(walletNetwork);
+      }
+      const signer = publicKey ?? await kit.getPublicKey();
+      publicKey = signer;
+      const response = await kit.sign({ xdr, publicKey: signer });
+      return response.signedXDR;
+    },
+    async startWalletConnect(metadata = options.walletConnectMetadata) {
+      if (!metadata) {
+        throw new Error("WalletConnect metadata is required before starting WalletConnect.");
+      }
+      await kit.startWalletConnect(metadata);
+      isWalletConnectStarted = true;
+      for (const callback of sessionDeletedCallbacks) {
+        kit.onSessionDeleted((sessionId) => {
+          publicKey = void 0;
+          callback(sessionId);
+        });
+      }
+    },
+    async connectWalletConnect(connectOptions) {
+      await kit.connectWalletConnect(connectOptions);
+      publicKey = void 0;
+    },
+    async getWalletConnectSessions() {
+      return kit.getSessions();
+    },
+    setWalletConnectSession(sessionId) {
+      kit.setSession(sessionId);
+      publicKey = void 0;
+    },
+    onWalletConnectSessionDeleted(callback) {
+      sessionDeletedCallbacks.add(callback);
+      if (!isWalletConnectStarted) {
+        return;
+      }
+      kit.onSessionDeleted((sessionId) => {
+        publicKey = void 0;
+        callback(sessionId);
+      });
+    }
+  };
+}
+function resolveWalletNetwork(networkPassphrase) {
+  if (networkPassphrase === "Test SDF Network ; September 2015") {
+    return import_stellar_wallets_kit.WalletNetwork.TESTNET;
+  }
+  if (networkPassphrase === "Public Global Stellar Network ; September 2015") {
+    return import_stellar_wallets_kit.WalletNetwork.PUBLIC;
+  }
+  return void 0;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createStellarWalletsKitAdapter
+});

package/dist/stellar-wallets-kit.d.cts

@@ -0,0 +1,46 @@
+import { StellarWalletsKit, WalletType, WalletNetwork, IConnectWalletConnectParams } from 'stellar-wallets-kit';
+import { C as CaatingaWalletAdapter } from './types-D4XEyX4J.cjs';
+import '@caatinga/core/browser';
+
+interface StellarWalletsKitMetadata {
+    name: string;
+    description: string;
+    url: string;
+    icons: string[];
+    projectId: string;
+}
+interface StellarWalletsKitAdapterOptions {
+    kit?: StellarWalletsKit;
+    network?: WalletNetwork;
+    selectedWallet?: WalletType;
+    walletConnectMetadata?: StellarWalletsKitMetadata;
+}
+interface StellarWalletsKitConnectOptions {
+    chains?: IConnectWalletConnectParams["chains"];
+    methods?: IConnectWalletConnectParams["methods"];
+    pairingTopic?: IConnectWalletConnectParams["pairingTopic"];
+}
+interface StellarWalletsKitSession {
+    id: string;
+    name: string;
+    description: string;
+    url: string;
+    icons: string;
+    accounts: Array<{
+        network: "pubnet" | "testnet";
+        publicKey: string;
+    }>;
+}
+interface StellarWalletsKitAdapter extends CaatingaWalletAdapter {
+    kit: StellarWalletsKit;
+    setWallet(wallet: WalletType): Promise<void>;
+    setNetwork(network: WalletNetwork): Promise<void>;
+    startWalletConnect(metadata?: StellarWalletsKitMetadata): Promise<void>;
+    connectWalletConnect(options?: StellarWalletsKitConnectOptions): Promise<void>;
+    getWalletConnectSessions(): Promise<StellarWalletsKitSession[]>;
+    setWalletConnectSession(sessionId: string): void;
+    onWalletConnectSessionDeleted(callback: (sessionId: string) => void): void;
+}
+declare function createStellarWalletsKitAdapter(options?: StellarWalletsKitAdapterOptions): StellarWalletsKitAdapter;
+
+export { type StellarWalletsKitAdapter, type StellarWalletsKitAdapterOptions, type StellarWalletsKitConnectOptions, type StellarWalletsKitMetadata, type StellarWalletsKitSession, createStellarWalletsKitAdapter };

package/dist/stellar-wallets-kit.d.ts

@@ -0,0 +1,46 @@
+import { StellarWalletsKit, WalletType, WalletNetwork, IConnectWalletConnectParams } from 'stellar-wallets-kit';
+import { C as CaatingaWalletAdapter } from './types-D4XEyX4J.js';
+import '@caatinga/core/browser';
+
+interface StellarWalletsKitMetadata {
+    name: string;
+    description: string;
+    url: string;
+    icons: string[];
+    projectId: string;
+}
+interface StellarWalletsKitAdapterOptions {
+    kit?: StellarWalletsKit;
+    network?: WalletNetwork;
+    selectedWallet?: WalletType;
+    walletConnectMetadata?: StellarWalletsKitMetadata;
+}
+interface StellarWalletsKitConnectOptions {
+    chains?: IConnectWalletConnectParams["chains"];
+    methods?: IConnectWalletConnectParams["methods"];
+    pairingTopic?: IConnectWalletConnectParams["pairingTopic"];
+}
+interface StellarWalletsKitSession {
+    id: string;
+    name: string;
+    description: string;
+    url: string;
+    icons: string;
+    accounts: Array<{
+        network: "pubnet" | "testnet";
+        publicKey: string;
+    }>;
+}
+interface StellarWalletsKitAdapter extends CaatingaWalletAdapter {
+    kit: StellarWalletsKit;
+    setWallet(wallet: WalletType): Promise<void>;
+    setNetwork(network: WalletNetwork): Promise<void>;
+    startWalletConnect(metadata?: StellarWalletsKitMetadata): Promise<void>;
+    connectWalletConnect(options?: StellarWalletsKitConnectOptions): Promise<void>;
+    getWalletConnectSessions(): Promise<StellarWalletsKitSession[]>;
+    setWalletConnectSession(sessionId: string): void;
+    onWalletConnectSessionDeleted(callback: (sessionId: string) => void): void;
+}
+declare function createStellarWalletsKitAdapter(options?: StellarWalletsKitAdapterOptions): StellarWalletsKitAdapter;
+
+export { type StellarWalletsKitAdapter, type StellarWalletsKitAdapterOptions, type StellarWalletsKitConnectOptions, type StellarWalletsKitMetadata, type StellarWalletsKitSession, createStellarWalletsKitAdapter };

package/dist/stellar-wallets-kit.js

@@ -0,0 +1,86 @@
+// src/adapters/stellar-wallets-kit.ts
+import {
+  StellarWalletsKit,
+  WalletNetwork,
+  WalletType
+} from "stellar-wallets-kit";
+function createStellarWalletsKitAdapter(options = {}) {
+  const kit = options.kit ?? new StellarWalletsKit({
+    network: options.network ?? WalletNetwork.TESTNET,
+    selectedWallet: options.selectedWallet ?? WalletType.XBULL
+  });
+  let publicKey;
+  let isWalletConnectStarted = false;
+  const sessionDeletedCallbacks = /* @__PURE__ */ new Set();
+  return {
+    kit,
+    async setWallet(wallet) {
+      await kit.setWallet(wallet);
+      publicKey = void 0;
+    },
+    async setNetwork(network) {
+      await kit.setNetwork(network);
+      publicKey = void 0;
+    },
+    async getPublicKey() {
+      publicKey = await kit.getPublicKey();
+      return publicKey;
+    },
+    async signTransaction({ xdr, networkPassphrase }) {
+      const walletNetwork = resolveWalletNetwork(networkPassphrase);
+      if (walletNetwork) {
+        await kit.setNetwork(walletNetwork);
+      }
+      const signer = publicKey ?? await kit.getPublicKey();
+      publicKey = signer;
+      const response = await kit.sign({ xdr, publicKey: signer });
+      return response.signedXDR;
+    },
+    async startWalletConnect(metadata = options.walletConnectMetadata) {
+      if (!metadata) {
+        throw new Error("WalletConnect metadata is required before starting WalletConnect.");
+      }
+      await kit.startWalletConnect(metadata);
+      isWalletConnectStarted = true;
+      for (const callback of sessionDeletedCallbacks) {
+        kit.onSessionDeleted((sessionId) => {
+          publicKey = void 0;
+          callback(sessionId);
+        });
+      }
+    },
+    async connectWalletConnect(connectOptions) {
+      await kit.connectWalletConnect(connectOptions);
+      publicKey = void 0;
+    },
+    async getWalletConnectSessions() {
+      return kit.getSessions();
+    },
+    setWalletConnectSession(sessionId) {
+      kit.setSession(sessionId);
+      publicKey = void 0;
+    },
+    onWalletConnectSessionDeleted(callback) {
+      sessionDeletedCallbacks.add(callback);
+      if (!isWalletConnectStarted) {
+        return;
+      }
+      kit.onSessionDeleted((sessionId) => {
+        publicKey = void 0;
+        callback(sessionId);
+      });
+    }
+  };
+}
+function resolveWalletNetwork(networkPassphrase) {
+  if (networkPassphrase === "Test SDF Network ; September 2015") {
+    return WalletNetwork.TESTNET;
+  }
+  if (networkPassphrase === "Public Global Stellar Network ; September 2015") {
+    return WalletNetwork.PUBLIC;
+  }
+  return void 0;
+}
+export {
+  createStellarWalletsKitAdapter
+};

package/dist/types-D4XEyX4J.d.cts

@@ -0,0 +1,86 @@
+import { CaatingaArtifacts } from '@caatinga/core/browser';
+
+interface CaatingaNetwork {
+    name: string;
+    rpcUrl: string;
+    networkPassphrase: string;
+}
+/**
+ * Wallet integration for browser-side signing.
+ *
+ * Implementations must reject the returned promise when the user dismisses or
+ * cancels signing (do not leave the promise pending indefinitely). Adapters may
+ * apply their own timeout. Caatinga optionally enforces {@link CaatingaClientConfig.walletTimeout}.
+ */
+interface CaatingaWalletAdapter {
+    getPublicKey(): Promise<string>;
+    signTransaction(input: {
+        xdr: string;
+        networkPassphrase: string;
+    }): Promise<string>;
+}
+interface CaatingaContractRegistration {
+    binding: unknown;
+    contractId?: string;
+}
+interface CaatingaClientConfig {
+    network: CaatingaNetwork;
+    artifacts: CaatingaArtifacts;
+    wallet: CaatingaWalletAdapter;
+    /** Optional timeout (ms) for wallet `getPublicKey` and `signTransaction`. No default when omitted. */
+    walletTimeout?: number;
+    contracts: Record<string, CaatingaContractRegistration>;
+}
+type CaatingaInvokeStatus = "built" | "prepared" | "signed" | "submitted" | "confirmed" | "failed";
+interface CaatingaInvokeOptions {
+    debugXdr?: boolean;
+    debugRaw?: boolean;
+}
+interface CaatingaReadOptions {
+    debugRaw?: boolean;
+}
+interface CaatingaInvokeResult<T = unknown> {
+    status: CaatingaInvokeStatus;
+    contract: string;
+    method: string;
+    contractId: string;
+    transactionHash?: string;
+    result?: T;
+    xdr?: {
+        unsigned?: string;
+        prepared?: string;
+        signed?: string;
+    };
+    raw?: unknown;
+}
+interface CaatingaReadResult<T = unknown> {
+    status: "simulated";
+    contract: string;
+    method: string;
+    contractId: string;
+    result: T;
+    raw?: unknown;
+}
+interface CaatingaXdrBuildResult {
+    contract: string;
+    method: string;
+    contractId: string;
+    unsignedXdr?: string;
+    preparedXdr: string;
+    raw?: unknown;
+}
+interface CaatingaBindingAdapter {
+    createClient(input: {
+        contractId: string;
+        publicKey: string;
+        rpcUrl: string;
+        networkPassphrase: string;
+    }): unknown;
+    callMethod(input: {
+        client: unknown;
+        method: string;
+        args?: Record<string, unknown>;
+    }): Promise<unknown>;
+}
+
+export type { CaatingaWalletAdapter as C, CaatingaBindingAdapter as a, CaatingaClientConfig as b, CaatingaContractRegistration as c, CaatingaXdrBuildResult as d, CaatingaInvokeOptions as e, CaatingaInvokeResult as f, CaatingaReadOptions as g, CaatingaReadResult as h, CaatingaInvokeStatus as i, CaatingaNetwork as j };

package/dist/types-D4XEyX4J.d.ts

@@ -0,0 +1,86 @@
+import { CaatingaArtifacts } from '@caatinga/core/browser';
+
+interface CaatingaNetwork {
+    name: string;
+    rpcUrl: string;
+    networkPassphrase: string;
+}
+/**
+ * Wallet integration for browser-side signing.
+ *
+ * Implementations must reject the returned promise when the user dismisses or
+ * cancels signing (do not leave the promise pending indefinitely). Adapters may
+ * apply their own timeout. Caatinga optionally enforces {@link CaatingaClientConfig.walletTimeout}.
+ */
+interface CaatingaWalletAdapter {
+    getPublicKey(): Promise<string>;
+    signTransaction(input: {
+        xdr: string;
+        networkPassphrase: string;
+    }): Promise<string>;
+}
+interface CaatingaContractRegistration {
+    binding: unknown;
+    contractId?: string;
+}
+interface CaatingaClientConfig {
+    network: CaatingaNetwork;
+    artifacts: CaatingaArtifacts;
+    wallet: CaatingaWalletAdapter;
+    /** Optional timeout (ms) for wallet `getPublicKey` and `signTransaction`. No default when omitted. */
+    walletTimeout?: number;
+    contracts: Record<string, CaatingaContractRegistration>;
+}
+type CaatingaInvokeStatus = "built" | "prepared" | "signed" | "submitted" | "confirmed" | "failed";
+interface CaatingaInvokeOptions {
+    debugXdr?: boolean;
+    debugRaw?: boolean;
+}
+interface CaatingaReadOptions {
+    debugRaw?: boolean;
+}
+interface CaatingaInvokeResult<T = unknown> {
+    status: CaatingaInvokeStatus;
+    contract: string;
+    method: string;
+    contractId: string;
+    transactionHash?: string;
+    result?: T;
+    xdr?: {
+        unsigned?: string;
+        prepared?: string;
+        signed?: string;
+    };
+    raw?: unknown;
+}
+interface CaatingaReadResult<T = unknown> {
+    status: "simulated";
+    contract: string;
+    method: string;
+    contractId: string;
+    result: T;
+    raw?: unknown;
+}
+interface CaatingaXdrBuildResult {
+    contract: string;
+    method: string;
+    contractId: string;
+    unsignedXdr?: string;
+    preparedXdr: string;
+    raw?: unknown;
+}
+interface CaatingaBindingAdapter {
+    createClient(input: {
+        contractId: string;
+        publicKey: string;
+        rpcUrl: string;
+        networkPassphrase: string;
+    }): unknown;
+    callMethod(input: {
+        client: unknown;
+        method: string;
+        args?: Record<string, unknown>;
+    }): Promise<unknown>;
+}
+
+export type { CaatingaWalletAdapter as C, CaatingaBindingAdapter as a, CaatingaClientConfig as b, CaatingaContractRegistration as c, CaatingaXdrBuildResult as d, CaatingaInvokeOptions as e, CaatingaInvokeResult as f, CaatingaReadOptions as g, CaatingaReadResult as h, CaatingaInvokeStatus as i, CaatingaNetwork as j };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caatinga/client",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Browser and Node client for Soroban smart contracts — connects generated bindings, Caatinga artifacts, and wallet adapters",
   "keywords": [
     "stellar",
@@ -38,6 +38,11 @@
       "types": "./dist/freighter.d.ts",
       "import": "./dist/freighter.js",
       "require": "./dist/freighter.cjs"
+    },
+    "./stellar-wallets-kit": {
+      "types": "./dist/stellar-wallets-kit.d.ts",
+      "import": "./dist/stellar-wallets-kit.js",
+      "require": "./dist/stellar-wallets-kit.cjs"
     }
   },
   "files": [
@@ -46,23 +51,28 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@caatinga/core": "^0.2.2"
+    "@caatinga/core": "^0.2.4"
   },
   "devDependencies": {
     "tsup": "^8.3.5",
+    "stellar-wallets-kit": "github:Creit-Tech/Stellar-Wallets-Kit#v0.0.7",
     "typescript": "^5.7.2",
     "vitest": "^2.1.8"
   },
   "peerDependencies": {
-    "@stellar/freighter-api": "^4.0.0"
+    "@stellar/freighter-api": "^4.0.0",
+    "stellar-wallets-kit": "github:Creit-Tech/Stellar-Wallets-Kit#v0.0.7"
   },
   "peerDependenciesMeta": {
     "@stellar/freighter-api": {
       "optional": true
+    },
+    "stellar-wallets-kit": {
+      "optional": true
     }
   },
   "scripts": {
-    "build": "tsup src/index.ts src/freighter.ts --format esm,cjs --dts",
+    "build": "tsup src/index.ts src/freighter.ts src/stellar-wallets-kit.ts --format esm,cjs --dts",
     "test": "vitest run --pool=threads",
     "pretypecheck": "pnpm --filter @caatinga/core run build",
     "typecheck": "tsc --noEmit"