Port Binding Generation

.github/workflows/e2e.yml

@@ -43,7 +43,7 @@ jobs:
     - uses: actions/setup-node@v4
       with:
         node-version: ${{ env.NODE }}
-    - uses: stellar/stellar-cli@v23.1.4
+    - uses: stellar/stellar-cli@v23.4.0
 
     # Install system dependencies required for Stellar CLI
     - name: Install system dependencies

README.md

@@ -27,6 +27,7 @@ The library provides:
    - [...with React Native](#usage-with-react-native)
    - [...with Expo](#usage-with-expo-managed-workflows)
    - [...with CloudFlare Workers](#usage-with-cloudflare-workers)
+ * [CLI](#cli): generate TypeScript bindings for Stellar smart contracts
  * [Developing](#developing): contribute to the project!
  * [Understanding `stellar-sdk` vs. `stellar-base`](#stellar-sdk-vs-stellar-base)
  * [License](#license)
@@ -200,6 +201,132 @@ Horizon.AxiosClient.defaults.adapter = fetchAdapter as any;
 
 All HTTP calls will use `fetch`, now, meaning it should work in the CloudFlare Worker environment.
 
+## CLI
+
+The SDK includes a command-line tool for generating TypeScript bindings from Stellar smart contracts. These bindings provide fully-typed client code with IDE autocompletion and compile-time type checking.
+
+### Running the CLI
+
+```shell
+# Using npx (no installation required)
+npx @stellar/stellar-sdk generate [options]
+
+# Or if installed globally
+stellar-js generate [options]
+```
+
+### Generating Bindings
+
+You can generate bindings from three different sources:
+
+#### From a local WASM file
+
+```shell
+npx @stellar/stellar-sdk generate \
+  --wasm ./path/to/wasm_file/my_contract.wasm \
+  --output-dir ./my-contract-client \
+  --contract-name my-contract
+```
+
+#### From a WASM hash on the network
+
+```shell
+npx @stellar/stellar-sdk generate \
+  --wasm-hash <hex-encoded-hash> \
+  --rpc-url https://soroban-testnet.stellar.org \
+  --network testnet \
+  --output-dir ./my-contract-client \
+  --contract-name my-contract
+```
+
+#### From a deployed contract ID
+
+```shell
+npx @stellar/stellar-sdk generate \
+  --contract-id CABC...XYZ \
+  --rpc-url https://soroban-testnet.stellar.org \
+  --network testnet \
+  --output-dir ./my-contract-client
+```
+
+#### With custom RPC server options
+
+For local development or when connecting to RPC servers that require authentication:
+
+```shell
+# Allow HTTP connections (useful for local development)
+npx @stellar/stellar-sdk generate \
+  --contract-id CABC...XYZ \
+  --rpc-url http://localhost:8000/soroban/rpc \
+  --network localnet \
+  --output-dir ./my-contract-client \
+  --allow-http
+
+# With custom timeout and headers
+npx @stellar/stellar-sdk generate \
+  --contract-id CABC...XYZ \
+  --rpc-url https://my-rpc-server.com \
+  --network mainnet \
+  --output-dir ./my-contract-client \
+  --timeout 30000 \
+  --headers '{"Authorization": "Bearer my-token"}'
+```
+
+### CLI Options
+
+| Option | Description |
+|--------|-------------|
+| `--wasm <path>` | Path to a local WASM file |
+| `--wasm-hash <hash>` | Hex-encoded hash of WASM blob on the network |
+| `--contract-id <id>` | Contract ID of a deployed contract |
+| `--rpc-url <url>` | Soroban RPC server URL (required for network sources) |
+| `--network <network>` | Network to use: `testnet`, `mainnet`, `futurenet`, or `localnet` (required for network sources) |
+| `--output-dir <dir>` | Output directory for generated bindings (required) |
+| `--contract-name <name>` | Name for the generated package (derived from filename if not provided) |
+| `--overwrite` | Overwrite existing files in the output directory |
+| `--allow-http` | Allow insecure HTTP connections to RPC server (default: false) |
+| `--timeout <ms>` | RPC request timeout in milliseconds |
+| `--headers <json>` | Custom headers as JSON object (e.g., `'{"Authorization": "Bearer token"}'`) |
+
+### Generated Output
+
+The CLI generates a complete npm package structure:
+
+```
+my-contract-client/
+├── src/
+│   ├── index.ts      # Barrel exports
+│   ├── client.ts     # Typed Client class with contract methods
+│   └── types.ts      # TypeScript interfaces for contract types
+├── package.json
+├── tsconfig.json
+├── README.md
+└── .gitignore
+```
+
+### Using Generated Bindings
+
+After generating, you can use the bindings in your project:
+
+```typescript
+import { Client } from './my-contract-client';
+
+const client = new Client({
+  contractId: 'CABC...XYZ',
+  networkPassphrase: Networks.TESTNET,
+  rpcUrl: 'https://soroban-testnet.stellar.org',
+  publicKey: keypair.publicKey(),
+  ...basicNodeSigner(keypair, Networks.TESTNET),
+});
+
+// Fully typed method calls with IDE autocompletion
+const result = await client.transfer({
+  from: 'GABC...',
+  to: 'GDEF...',
+  amount: 1000n,
+});
+```
+
 ## Developing
 
 So you want to contribute to the library: welcome! Whether you're working on a fork or want to make an upstream request, the dev-test loop is pretty straightforward.

bin/stellar-js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+// Entry point for the stellar CLI
+require("../lib/cli/index.js").runCli();

package.json

@@ -21,8 +21,12 @@
   "files": [
     "/types",
     "/lib",
-    "/dist"
+    "/dist",
+    "/bin"
   ],
+  "bin": {
+    "stellar-js": "./bin/stellar-js"
+  },
   "exports": {
     ".": {
       "browser": "./dist/stellar-sdk.min.js",
@@ -107,6 +111,7 @@
     "fmt": "yarn _prettier && yarn eslint src/ --fix",
     "preversion": "yarn clean && yarn _prettier && yarn build:prod && yarn test",
     "prepare": "yarn build:prod && yarn setup",
+    "download-sac-spec": "node scripts/download-sac-spec.js",
     "_build": "yarn build:node:all && yarn build:browser:all",
     "_babel": "babel --extensions '.ts' --out-dir ${OUTPUT_DIR:-lib} src/",
     "_nyc": "node node_modules/.bin/nyc --nycrc-path config/.nycrc",
@@ -196,6 +201,7 @@
     "@stellar/stellar-base": "^14.0.4",
     "axios": "^1.13.2",
     "bignumber.js": "^9.3.1",
+    "commander": "^14.0.2",
     "eventsource": "^2.0.2",
     "feaxios": "^0.0.23",
     "randombytes": "^2.1.0",

scripts/download-sac-spec.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+
+import https from "https";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+// Get __dirname equivalent in ESM
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Get repo root
+const REPO_ROOT = path.join(__dirname, "..");
+
+// URLs and paths
+const REPO_URL =
+  "https://raw.githubusercontent.com/stellar/stellar-asset-contract-spec/main/stellar-asset-spec.xdr";
+const TS_FILE = path.join(REPO_ROOT, "src/bindings/sac-spec.ts");
+
+console.log("Downloading Stellar Asset Contract spec from GitHub...");
+
+// Download file
+https
+  .get(REPO_URL, (response) => {
+    if (response.statusCode !== 200) {
+      console.error(`✗ Failed to download: HTTP ${response.statusCode}`);
+      process.exit(1);
+    }
+
+    const chunks = [];
+
+    response.on("data", (chunk) => {
+      chunks.push(chunk);
+    });
+
+    response.on("end", () => {
+      const buffer = Buffer.concat(chunks);
+
+      // Verify file has content
+      if (buffer.length === 0) {
+        console.error("✗ Downloaded file is empty");
+        process.exit(1);
+      }
+
+      console.log("✓ Successfully downloaded file");
+      console.log(`  Size: ${buffer.length} bytes`);
+
+      // Convert to base64
+      console.log("Converting to base64...");
+      const base64Content = buffer.toString("base64");
+
+      if (!base64Content) {
+        console.error("✗ Base64 conversion failed");
+        process.exit(1);
+      }
+
+      // Update TypeScript file
+      console.log(`Updating ${path.relative(REPO_ROOT, TS_FILE)}...`);
+      const tsContent = [
+        "// Auto-generated by scripts/download-sac-spec.sh",
+        "// Do not edit manually - run the script to update",
+        `export const SAC_SPEC = "${base64Content}";`,
+        "", // trailing newline
+      ].join("\n");
+
+      try {
+        fs.writeFileSync(TS_FILE, tsContent, "utf8");
+        console.log(
+          `✓ Successfully updated ${path.relative(REPO_ROOT, TS_FILE)}`,
+        );
+      } catch (error) {
+        console.error(`✗ Failed to write file: ${error.message}`);
+        process.exit(1);
+      }
+
+      console.log("✓ Done");
+    });
+  })
+  .on("error", (error) => {
+    console.error(`✗ Error: ${error.message}`);
+    process.exit(1);
+  });