feat: auto-generate TypeScript bindings for Stellar contracts

.github/workflows/ci.yml

@@ -58,12 +58,40 @@ jobs:
         working-directory: stellar
     steps:
       - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install pnpm
+        run: npm install -g pnpm
+
+      - name: Install Node dependencies
+        run: pnpm install
+        working-directory: .
+
+      - name: Setup Stellar CLI
+        uses: stellar/setup-soroban@v1
+        with:
+          version: "22.0.1"
+
       - uses: dtolnay/rust-toolchain@stable
         with:
           components: rustfmt
+          targets: wasm32-unknown-unknown
+
       - run: cargo fmt --all --check
       - run: cargo test --workspace
 
+      - name: Generate Stellar TypeScript bindings
+        run: pnpm bindings:stellar
+        working-directory: .
+
+      - name: Check for bindings drift (diff detection)
+        run: git diff --exit-code
+        working-directory: .
+
   stellar-nightly:
     if: github.event_name == 'schedule'
     runs-on: ubuntu-latest

.gitignore

@@ -18,3 +18,7 @@ solana/.anchor/
 # CKB
 ckb/target/
 ckb/build/
+
+# Root Node/TS Build & Dependencies
+node_modules/
+dist/

README.md

@@ -79,6 +79,36 @@ WRAITH_PROPTEST_CASES=16384 cargo test --workspace --test properties
 
 By default each property runs at least 1,024 generated cases. The scheduled `stellar-nightly` CI job raises that to 16,384 cases through `WRAITH_PROPTEST_CASES`. Add new properties beside the contract they cover so failures point directly at the affected crate.
 
+#### Generated Bindings
+
+TypeScript bindings for the Stellar/Soroban contracts are automatically generated under `stellar/bindings/typescript/` and checked into the repository. These provide type-safe, compiled TS clients that the SDK can import directly.
+
+To regenerate the bindings locally (offline using compiled `.wasm` files):
+1. Install Node.js dependencies at the repository root:
+   ```bash
+   pnpm install
+   ```
+2. Compile the contracts to WASM (this is also done automatically by the script if WASM files are missing):
+   ```bash
+   cd stellar && cargo build --target wasm32-unknown-unknown --release && cd ..
+   ```
+3. Run the bindings generator script from the root:
+   ```bash
+   pnpm bindings:stellar
+   ```
+
+To generate the bindings against live deployed contract IDs on testnet:
+1. Specify the contract IDs in `stellar/contract-ids.json` or as environment variables (e.g., `STEALTH_REGISTRY_CONTRACT_ID=...`).
+2. Run the generation script from the root:
+   ```bash
+   pnpm bindings:stellar
+   ```
+
+**When to Regenerate:**
+You must regenerate and commit the updated bindings whenever:
+1. You modify any Soroban contract function signatures, events, or custom types in Rust.
+2. A new contract deployment is made on testnet and you want to update the bindings' target client references.
+
 ### Solana
 
 ```bash

package.json

@@ -0,0 +1,15 @@
+{
+  "name": "wraith-contracts-root",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "bindings:stellar": "tsx stellar/scripts/generate-bindings.ts",
+    "build:stellar": "pnpm bindings:stellar && cd stellar && cargo build --target wasm32-unknown-unknown --release"
+  },
+  "devDependencies": {
+    "@stellar/stellar-sdk": "^15.1.0",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.0"
+  }
+}