Handle built-in Stellar Asset Contracts (SACs) in contract.Client.from (#1501)

* Handle SAC in contract.Client.from

* Docs updated

* Fix tests

* Optimize

* Fix and update docs

* Update error response

* Rollup: enable inlineDynamicImports

* Update error message + outdated comment

* Add rpc.Server.queryContract for one-line read-only contract calls (#1502)

* Add rpc.Server.queryContract for one-line read-only contract calls

* Sanitize method name

* Check only contract methods before invoking

* e2e test happy path

* Make contract.Client factories generic for typed runtime clients (#1504)

* Make contract.Client factories generic for typed runtime clients

* Add `rpc.Server.getContractMethods` for contract method discovery (#1505)

* Add rpc.Server.getContractMethods for contract method discovery

* Document queryContract and getContractMethods in the invoke-a-contract guide

* Type the contract.Client examples in the invoke and auth guides

* Updated changelog

* Return { result, isReadCall } from queryContract (#1511)

Author: quietbits

.gitignore

@@ -42,3 +42,4 @@ config/tsconfig.tmp.json
 # scratch: per-guide tests, never shipped
 test-guides/
 .vuln-hunt/
+scratch/

CHANGELOG.md

@@ -6,6 +6,18 @@ A breaking change will get clearly marked in this log.
 
 ## Unreleased
 
+### Added
+- `rpc.Server.queryContract<T>(contractId, method, args?, networkPassphrase?)`: a one-line read-only contract call that builds a client, simulates the method, and returns `{ result, isReadCall }` — the spec-decoded return value plus whether this specific call is a signature-free read that wrote no state (per-call, reflecting the given `args`). No manual transaction assembly, signing, or submission. Works for both Wasm contracts and built-in Stellar Asset Contracts (SACs) ([#1502](https://github.com/stellar/js-stellar-sdk/pull/1502)).
+- `rpc.Server.getContractMethods(contractId, networkPassphrase?)`: lists a contract's callable methods and their signatures (name, inputs, outputs, and doc string) for discovery and tooling, without invoking or simulating anything. Adds the `Api.ContractMethod` and `Api.ContractMethodInput` types ([#1502](https://github.com/stellar/js-stellar-sdk/pull/1502)).
+- `rpc.Server.getContractInstance(contractId)`: returns a contract's `xdr.ScContractInstance` (its executable and instance storage) ([#1501](https://github.com/stellar/js-stellar-sdk/pull/1501)).
+- `contract.Client.from`, `fromWasm`, and `fromWasmHash` are now generic (`<T>`) and return `Client & T`, giving typed, autocompleted contract methods without code generation. The type parameter defaults to `unknown`, so existing untyped calls are unchanged ([#1502](https://github.com/stellar/js-stellar-sdk/pull/1502)).
+- `ClientOptions.server`: pass an existing `rpc.Server` to `contract.Client.from` to reuse its transport (headers, interceptors, `allowHttp`) instead of constructing a new one ([#1502](https://github.com/stellar/js-stellar-sdk/pull/1502)).
+
+### Changed
+- `contract.Client.from` now supports built-in Stellar Asset Contracts (SACs): when the contract's executable is a SAC, the client is built from the embedded SAC spec (lazily imported so bundlers can code-split it out of the common path) instead of downloading Wasm, which a SAC has none of on-chain ([#1501](https://github.com/stellar/js-stellar-sdk/pull/1501)).
+- `rpc.Server.getContractWasmByContractId` now rejects a SAC with a structured `{ code: 400 }` error pointing to `contract.Client.from`, instead of failing while decoding a nonexistent Wasm hash; the not-found rejection is now `{ code: 404, message: "Could not obtain contract instance from server" }` ([#1501](https://github.com/stellar/js-stellar-sdk/pull/1501)).
+- The UMD (`dist/`) build now sets `inlineDynamicImports` so the single-file bundle stays whole despite the SAC spec's lazy `import()` ([#1501](https://github.com/stellar/js-stellar-sdk/pull/1501)).
+
 ## [v16.0.1](https://github.com/stellar/js-stellar-sdk/compare/v16.0.0...v16.0.1)
 
 ### Fixed

docs/guides/06-invoke-a-contract.md

@@ -23,7 +23,8 @@ free and safe to repeat.
   [Deploy the Increment Contract](https://developers.stellar.org/docs/build/smart-contracts/getting-started/deploy-increment-contract)
   tutorial once (about 20 to 30 minutes), then paste the contract ID it prints
   into `contractId` below. You will not touch the CLI again in this guide.
-  Generating a typed client from a contract is covered later in the series.
+  This guide types the client with a small hand-written interface; generating one
+  from a contract's spec is covered later in the series.
 - The examples use testnet RPC at `https://soroban-testnet.stellar.org`.
 
 ## Connect and load the contract
@@ -41,9 +42,18 @@ import { contract, Keypair, Networks } from "@stellar/stellar-sdk";
 const rpcUrl = "https://soroban-testnet.stellar.org";
 const networkPassphrase = Networks.TESTNET;
 
+// Describe just the methods you call. `Client.from<T>()` uses this to type the
+// returned client, so the calls below are checked and autocompleted — no code
+// generation needed.
+interface IncrementContract {
+  increment: (
+    options?: contract.MethodOptions,
+  ) => Promise<contract.AssembledTransaction<number>>;
+}
+
 const { signTransaction } = contract.basicNodeSigner(keypair, networkPassphrase);
 
-const client = await contract.Client.from({
+const client = await contract.Client.from<IncrementContract>({
   contractId,
   rpcUrl,
   networkPassphrase,
@@ -54,10 +64,65 @@ const client = await contract.Client.from({
 
 Here `keypair` is your funded account from
 [Connect and Fund an Account](/guides/01-connect-and-fund/) and `contractId` is
-your deployed contract's `C...` ID. Because the client is built from the live
-contract at runtime, its methods are **not typed**: TypeScript does not know
-`client.increment` exists, so calls below use `(client as any)`. A fully typed
-client comes from generating bindings, covered later in the series.
+your deployed contract's `C...` ID. The client is built from the live contract at
+runtime, so TypeScript cannot infer its methods on its own. Passing an interface
+to [`Client.from<T>()`](/reference/contracts-client/#contractclient) types them:
+`client.increment()` below is fully typed and autocompleted, with no code
+generation. For a contract with many methods, generate that interface from its
+spec (covered later in the series) rather than writing it by hand.
+
+## Query contract state
+
+Sometimes you only want to **inspect** a contract or **read** a value from it, not
+change anything. For that, `rpc.Server` has two one-line shortcuts that build the
+contract's interface for you — including the built-in spec for Stellar Asset
+Contracts (SACs) — so they work from just a contract ID, with no client setup.
+
+[`getContractMethods`](/reference/network-rpc/#servergetcontractmethodscontractid-networkpassphrase)
+lists a contract's callable methods and their signatures, which is handy when you
+are inspecting a contract you did not write. The spec it reports carries no
+read/write flag, so to learn whether a *specific* call would change state, invoke
+it with `queryContract` and read its `isReadCall` (see below).
+[`queryContract`](/reference/network-rpc/#serverquerycontractcontractid-method-args-networkpassphrase)
+runs a **read-only**
+call and returns the decoded result. It simulates the call the same way the preview
+below does, so it needs no signing or fee, but it hands you the value directly. Here
+both run against a token contract — discover its methods, then read one:
+
+```ts
+import { rpc } from "@stellar/stellar-sdk";
+
+const server = new rpc.Server(rpcUrl);
+
+// Discover what the contract exposes, from just its ID.
+const methods = await server.getContractMethods(tokenId);
+// [
+//   { name: "decimals", inputs: [], outputs: ["U32"] },
+//   { name: "balance", inputs: [{ name: "id", type: "Address" }], outputs: ["I128"] },
+//   { name: "transfer", inputs: [...], outputs: [] },
+// ]
+
+// Read one of its read-only methods in a single line.
+const { result: decimals, isReadCall } = await server.queryContract<number>(
+  tokenId,
+  "decimals",
+);
+
+const { result: balance } = await server.queryContract<bigint>(
+  tokenId,
+  "balance",
+  {
+    id: "G...", // named arguments, keyed by the method's parameter names
+  },
+);
+```
+
+Alongside the decoded `result`, `queryContract` returns `isReadCall`: whether
+*this* call — for the exact arguments given — wrote no state and needed no
+signature. It is per-call, not a fixed property of the method. Since
+`queryContract` never signs or sends, `isReadCall: false` means the `result` is
+only a simulation preview of a call that would change state; to apply such a
+change you build a client and sign a transaction, as shown next.
 
 ## Preview a call with simulation
 
@@ -68,7 +133,7 @@ no signature. Read the predicted return value from
 [`tx.result`](/reference/contracts-client/#contractassembledtransaction):
 
 ```ts
-const tx = await (client as any).increment();
+const tx = await client.increment();
 
 tx.result; // the value the call would return; nothing has been sent
 ```
@@ -113,6 +178,12 @@ const rpcUrl = "https://soroban-testnet.stellar.org";
 const networkPassphrase = Networks.TESTNET;
 const contractId = "C..."; // your deployed increment contract (see Prerequisites)
 
+interface IncrementContract {
+  increment: (
+    options?: contract.MethodOptions,
+  ) => Promise<contract.AssembledTransaction<number>>;
+}
+
 async function main() {
   const server = new rpc.Server(rpcUrl);
   const keypair = Keypair.random();
@@ -125,7 +196,7 @@ async function main() {
     // Fund a throwaway account to invoke from (the RPC-side friendbot).
     await server.fundAddress(keypair.publicKey());
 
-    const client = await contract.Client.from({
+    const client = await contract.Client.from<IncrementContract>({
       contractId,
       rpcUrl,
       networkPassphrase,
@@ -134,7 +205,7 @@ async function main() {
     });
 
     // Preview the call for free with simulation.
-    const tx = await (client as any).increment();
+    const tx = await client.increment();
     console.log("preview:", tx.result);
 
     // Sign and send to apply it on-chain.

docs/guides/07-contract-auth.md

@@ -108,7 +108,7 @@ authorization entry that account must sign. Build the transaction as in
 need to sign:
 
 ```ts
-const tx = await (client as any).increment({ user: signer.publicKey(), value: 1 });
+const tx = await client.increment({ user: signer.publicKey(), value: 1 });
 
 tx.needsNonInvokerSigningBy(); // [signer.publicKey()]
 ```
@@ -218,6 +218,13 @@ const rpcUrl = "https://soroban-testnet.stellar.org";
 const networkPassphrase = Networks.TESTNET;
 const contractId = "C..."; // your deployed Auth contract (see Prerequisites)
 
+interface AuthContract {
+  increment: (
+    args: { user: string; value: number },
+    options?: contract.MethodOptions,
+  ) => Promise<contract.AssembledTransaction<number>>;
+}
+
 async function main() {
   const server = new rpc.Server(rpcUrl);
 
@@ -234,7 +241,7 @@ async function main() {
       source,
       networkPassphrase,
     );
-    const client = await contract.Client.from({
+    const client = await contract.Client.from<AuthContract>({
       contractId,
       rpcUrl,
       networkPassphrase,
@@ -243,7 +250,7 @@ async function main() {
     });
 
     // A call that requires `signer` (not the source) to authorize it.
-    const tx = await (client as any).increment({
+    const tx = await client.increment({
       user: signer.publicKey(),
       value: 1,
     });

docs/reference/contracts-client.md

@@ -632,9 +632,9 @@ transaction.
 class Client {
   constructor(spec: Spec, options: ClientOptions);
   static deploy<T = Client>(args: Record<string, any> | null, options: MethodOptions & Omit<ClientOptions, "contractId"> & { address?: string; format?: "base64" | "hex"; salt?: Uint8Array<ArrayBufferLike> | Buffer<ArrayBufferLike>; wasmHash: string | Buffer<ArrayBufferLike> }): Promise<AssembledTransaction<T>>;
-  static from(options: ClientOptions): Promise<Client>;
-  static fromWasm(wasm: Buffer, options: ClientOptions): Promise<Client>;
-  static fromWasmHash(wasmHash: string | Buffer<ArrayBufferLike>, options: ClientOptions, format: "base64" | "hex" = "hex"): Promise<Client>;
+  static from<T = unknown>(options: ClientOptions): Promise<Client & T>;
+  static fromWasm<T = unknown>(wasm: Buffer, options: ClientOptions): Promise<Client & T>;
+  static fromWasmHash<T = unknown>(wasmHash: string | Buffer<ArrayBufferLike>, options: ClientOptions, format: "base64" | "hex" = "hex"): Promise<Client & T>;
   readonly options: ClientOptions;
   readonly spec: Spec;
   txFromJSON<T>(json: string): AssembledTransaction<T>;
@@ -674,8 +674,12 @@ static deploy<T = Client>(args: Record<string, any> | null, options: MethodOptio
 
 Generates a Client instance from the provided ClientOptions, which must include the contractId and rpcUrl.
 
+If the contract is a built-in Stellar Asset Contract (SAC), the embedded
+SAC spec is used instead of downloading Wasm, since a SAC has no Wasm
+executable on-chain.
+
 ```ts
-static from(options: ClientOptions): Promise<Client>;
+static from<T = unknown>(options: ClientOptions): Promise<Client & T>;
 ```
 
 **Parameters**
@@ -690,14 +694,24 @@ A Promise that resolves to a Client instance.
 
 - If the provided options object does not contain both rpcUrl and contractId.
 
-**Source:** [src/contract/client.ts:188](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/client.ts#L188)
+**Example**
+
+```ts
+interface MyContract {
+  increment: (opts?: MethodOptions) => Promise<AssembledTransaction<number>>;
+}
+const client = await contract.Client.from<MyContract>(options);
+const tx = await client.increment(); // typed
+```
+
+**Source:** [src/contract/client.ts:237](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/client.ts#L237)
 
 ### `Client.fromWasm(wasm, options)`
 
 Generates a Client instance from the provided ClientOptions and the contract's wasm binary.
 
 ```ts
-static fromWasm(wasm: Buffer, options: ClientOptions): Promise<Client>;
+static fromWasm<T = unknown>(wasm: Buffer, options: ClientOptions): Promise<Client & T>;
 ```
 
 **Parameters**
@@ -713,15 +727,25 @@ A Promise that resolves to a Client instance.
 
 - If the contract spec cannot be obtained from the provided wasm binary.
 
-**Source:** [src/contract/client.ts:176](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/client.ts#L176)
+**Example**
+
+```ts
+interface MyContract {
+  increment: (opts?: MethodOptions) => Promise<AssembledTransaction<number>>;
+}
+const client = await contract.Client.fromWasm<MyContract>(wasm, options);
+const tx = await client.increment(); // typed
+```
+
+**Source:** [src/contract/client.ts:204](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/client.ts#L204)
 
 ### `Client.fromWasmHash(wasmHash, options, format)`
 
 Generates a Client instance from the provided ClientOptions and the contract's wasm hash.
 The wasmHash can be provided in either hex or base64 format.
 
 ```ts
-static fromWasmHash(wasmHash: string | Buffer<ArrayBufferLike>, options: ClientOptions, format: "base64" | "hex" = "hex"): Promise<Client>;
+static fromWasmHash<T = unknown>(wasmHash: string | Buffer<ArrayBufferLike>, options: ClientOptions, format: "base64" | "hex" = "hex"): Promise<Client & T>;
 ```
 
 **Parameters**
@@ -738,7 +762,17 @@ A Promise that resolves to a Client instance.
 
 - If the provided options object does not contain an rpcUrl.
 
-**Source:** [src/contract/client.ts:148](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/client.ts#L148)
+**Example**
+
+```ts
+interface MyContract {
+  increment: (opts?: MethodOptions) => Promise<AssembledTransaction<number>>;
+}
+const client = await contract.Client.fromWasmHash<MyContract>(hash, options);
+const tx = await client.increment(); // typed
+```
+
+**Source:** [src/contract/client.ts:162](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/client.ts#L162)
 
 ### `client.options`
 
@@ -766,7 +800,7 @@ txFromJSON<T>(json: string): AssembledTransaction<T>;
 
 - **`json`** — `string` (required)
 
-**Source:** [src/contract/client.ts:201](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/client.ts#L201)
+**Source:** [src/contract/client.ts:269](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/client.ts#L269)
 
 ### `client.txFromXDR(xdrBase64)`
 
@@ -778,7 +812,7 @@ txFromXDR<T>(xdrBase64: string): AssembledTransaction<T>;
 
 - **`xdrBase64`** — `string` (required)
 
-**Source:** [src/contract/client.ts:214](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/client.ts#L214)
+**Source:** [src/contract/client.ts:282](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/client.ts#L282)
 
 ## contract.DEFAULT_TIMEOUT