feat: auto-generate TypeScript bindings from the contract ABI

.github/workflows/soroban.yml

@@ -32,3 +32,38 @@ jobs:
 
       - name: Build contract to WASM
         run: cargo build --target wasm32-unknown-unknown --release
+
+  bindings-check:
+    name: Bindings up-to-date
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Setup Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: wasm32-unknown-unknown
+
+      - name: Cache cargo registry and build artifacts
+        uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: ./payment_router
+
+      - name: Download stellar CLI (pinned)
+        run: |
+          curl -sL -o /tmp/stellar-cli.tar.gz \
+            "https://github.com/stellar/stellar-cli/releases/download/v27.1.0/stellar-cli-27.1.0-x86_64-unknown-linux-gnu.tar.gz"
+          tar -xzf /tmp/stellar-cli.tar.gz -C /tmp
+          chmod +x /tmp/stellar
+          /tmp/stellar --version
+
+      - name: Regenerate contract bindings
+        run: STELLAR_CLI=/tmp/stellar ./scripts/generate-bindings.sh
+
+      - name: Fail if generated bindings drifted
+        run: |
+          if ! git diff --exit-code -- packages/; then
+            echo "::error::packages/types is out of date. Run 'npm run generate:bindings' and commit the result."
+            exit 1
+          fi

README.md

@@ -140,6 +140,26 @@ cd payment_router
 cargo build
 ```
 
+### Contract TypeScript bindings
+
+The TypeScript client for the `payment_router` contract lives in
+[`packages/types`](packages/types) and is **auto-generated** from the contract
+ABI, so the React dashboard gets end-to-end type safety with the Rust contract
+instead of manually copying contract IDs and argument shapes.
+
+Regenerate the bindings after any change to the contract's public interface
+(the contract must build with the `wasm32-unknown-unknown` target, and the
+`stellar` CLI must be on your PATH):
+
+```bash
+npm run generate:bindings
+```
+
+The result is committed to `packages/types` and consumed by the frontend as
+`@stellar-tags/payment-router` (a `file:` dependency). The `bindings-check` CI
+job fails the build if the checked-in bindings ever drift from the contract
+ABI.
+
 ## Webhook signature verification
 
 Every webhook delivery includes an HMAC-SHA256 signature in the

package.json

@@ -7,6 +7,7 @@
     "lint": "eslint .",
     "prepare": "husky",
     "load:test": "artillery run artillery.yml",
+    "generate:bindings": "bash scripts/generate-bindings.sh",
     "contract:build": "node scripts/deploy.js build",
     "contract:deploy": "node scripts/deploy.js deploy",
     "contract:upgrade": "node scripts/deploy.js upgrade"

packages/types/.gitignore

@@ -0,0 +1,2 @@
+node_modules/
+out/

packages/types/README.md

@@ -0,0 +1,54 @@
+# @stellar-tags/payment-router JS
+
+JS library for interacting with [Soroban](https://soroban.stellar.org/) smart contract `@stellar-tags/payment-router` via Soroban RPC.
+
+This library was automatically generated by Soroban CLI using a command similar to:
+
+```bash
+soroban contract bindings ts \
+  --rpc-url INSERT_RPC_URL_HERE \
+  --network-passphrase "INSERT_NETWORK_PASSPHRASE_HERE" \
+  --contract-id INSERT_CONTRACT_ID_HERE \
+  --output-dir ./path/to/payment-router
+```
+
+The network passphrase and contract ID are exported from [index.ts](./src/index.ts) in the `networks` constant. If you are the one who generated this library and you know that this contract is also deployed to other networks, feel free to update `networks` with other valid options. This will help your contract consumers use this library more easily.
+
+# To publish or not to publish
+
+This library is suitable for publishing to NPM. You can publish it to NPM using the `npm publish` command.
+
+But you don't need to publish this library to NPM to use it. You can add it to your project's `package.json` using a file path:
+
+```json
+"dependencies": {
+  "@stellar-tags/payment-router": "./path/to/this/folder"
+}
+```
+
+However, we've actually encountered [frustration](https://github.com/stellar/soroban-example-dapp/pull/117#discussion_r1232873560) using local libraries with NPM in this way. Though it seems a bit messy, we suggest generating the library directly to your `node_modules` folder automatically after each install by using a `postinstall` script. We've had the least trouble with this approach. NPM will automatically remove what it sees as erroneous directories during the `install` step, and then regenerate them when it gets to your `postinstall` step, which will keep the library up-to-date with your contract.
+
+```json
+"scripts": {
+  "postinstall": "soroban contract bindings ts --rpc-url INSERT_RPC_URL_HERE --network-passphrase \"INSERT_NETWORK_PASSPHRASE_HERE\" --id INSERT_CONTRACT_ID_HERE --name @stellar-tags/payment-router"
+}
+```
+
+Obviously you need to adjust the above command based on the actual command you used to generate the library.
+
+# Use it
+
+Now that you have your library up-to-date and added to your project, you can import it in a file and see inline documentation for all of its exported methods:
+
+```js
+import { Contract, networks } from "@stellar-tags/payment-router"
+
+const contract = new Contract({
+  ...networks.futurenet, // for example; check which networks this library exports
+  rpcUrl: '...', // use your own, or find one for testing at https://soroban.stellar.org/docs/reference/rpc#public-rpc-providers
+})
+
+contract.|
+```
+
+As long as your editor is configured to show JavaScript/TypeScript documentation, you can pause your typing at that `|` to get a list of all exports and inline-documentation for each. It exports a separate [async](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function) function for each method in the smart contract, with documentation for each generated from the comments the contract's author included in the original source code.

packages/types/package.json

@@ -0,0 +1,20 @@
+{
+  "version": "0.0.0",
+  "name": "@stellar-tags/payment-router",
+  "type": "module",
+  "exports": "./src/index.ts",
+  "typings": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc"
+  },
+  "dependencies": {
+    "@stellar/stellar-sdk": "^16.0.1",
+    "buffer": "6.0.3"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.2"
+  },
+  "description": "Auto-generated TypeScript client for the stellar-tags payment_router Soroban contract. Generated from the contract ABI by scripts/generate-bindings.sh — do not edit by hand.",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts"
+}