typescript sdk

.github/workflows/typescript-e2e.yml

@@ -74,6 +74,12 @@ jobs:
             -o Dpkg::Options::="--force-confdef" -o Dpkg::Options::="--force-confold" \
             build-essential clang curl git make libssl-dev llvm libudev-dev protobuf-compiler pkg-config
 
+      - name: Install TypeScript SDK dependencies
+        run: npm --prefix sdk/typescript-sdk ci
+
+      - name: Type-check TypeScript SDK
+        run: npm --prefix sdk/typescript-sdk run typecheck
+
       - name: Install e2e dependencies
         working-directory: ts-tests
         run: pnpm install --frozen-lockfile
@@ -83,6 +89,51 @@ jobs:
           cd ts-tests
           pnpm run fmt
 
+  build-typescript-sdk:
+    runs-on: [self-hosted, fireactions-heavy]
+    needs: [trusted-pr, typescript-formatting]
+    timeout-minutes: 60
+    steps:
+      - name: Check-out repository
+        uses: actions/checkout@v4
+
+      - name: Install system dependencies
+        run: |
+          sudo DEBIAN_FRONTEND=noninteractive NEEDRESTART_MODE=a apt-get update
+          sudo DEBIAN_FRONTEND=noninteractive NEEDRESTART_MODE=a apt-get install -y --no-install-recommends \
+            -o Dpkg::Options::="--force-confdef" -o Dpkg::Options::="--force-confold" \
+            build-essential clang curl git make libssl-dev llvm libudev-dev protobuf-compiler pkg-config
+
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@4be7066ada62dd38de10e7b70166bc74ed198c30 # stable
+
+      - name: Utilize Shared Rust Cache
+        uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
+        with:
+          key: typescript-sdk
+          cache-on-failure: true
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ts-tests/.nvmrc
+
+      - name: Build and test TypeScript SDK
+        run: |
+          npm --prefix sdk/typescript-sdk ci
+          npm --prefix sdk/typescript-sdk run check
+
+      - name: Upload TypeScript SDK build
+        uses: actions/upload-artifact@v4
+        with:
+          name: bittensor-typescript-sdk
+          path: |
+            sdk/typescript-sdk/dist
+            sdk/typescript-sdk/native.cjs
+            sdk/typescript-sdk/native.generated.d.ts
+            sdk/typescript-sdk/*.node
+          if-no-files-found: error
+
   # Build the node binary in both variants and share as artifacts.
   build:
     runs-on: [self-hosted, fireactions-heavy]
@@ -129,7 +180,7 @@ jobs:
           if-no-files-found: error
 
   run-e2e-tests:
-    needs: [trusted-pr, build]
+    needs: [trusted-pr, build, build-typescript-sdk]
     runs-on: [self-hosted, fireactions-heavy]
     timeout-minutes: 30
 
@@ -165,6 +216,12 @@ jobs:
       - name: Make binary executable
         run: chmod +x target/release/node-subtensor
 
+      - name: Download TypeScript SDK build
+        uses: actions/download-artifact@v4
+        with:
+          name: bittensor-typescript-sdk
+          path: sdk/typescript-sdk
+
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:

Cargo.toml

@@ -32,6 +32,7 @@ members = [
 	"primitives/*",
 	"runtime",
 	"sdk/bittensor-core",
+	"sdk/typescript-sdk/native",
 	"sdk/bittensor-core-py",
 	"support/*",
 	"chain-extensions",

sdk/typescript-sdk/.gitignore

@@ -0,0 +1,7 @@
+node_modules/
+dist/
+native.cjs
+native.generated.d.ts
+*.node
+*.node.map
+npm-debug.log*

sdk/typescript-sdk/README.md

@@ -0,0 +1,71 @@
+# `@bittensor/sdk`
+
+The monorepo's TypeScript SDK. It lives in its own `sdk/typescript-sdk`
+package and is a deliberately thin Node-API wrapper around the sibling
+`bittensor-core` Rust crate.
+
+All chain-defined work runs in Rust:
+
+- sr25519/ed25519 keys, signatures, SS58, and wallet keyfiles;
+- SCALE encoding and decoding, runtime metadata, storage keys, calls, and
+  signed extrinsics;
+- RFC-0078 metadata digests and Ledger proofs;
+- drand timelock encryption and epoch-schedule simulation;
+- ML-KEM/XChaCha20 MEV-shield envelopes; and
+- Ledger HID signing.
+
+The TypeScript layer is limited to JavaScript-friendly names and defaults,
+lossless `Buffer`/`bigint`/`Map` boundary conversion, error classes, and
+compatibility adapters for the signer objects expected by Polkadot.js,
+Polkadot API, and Moonwall.
+
+The package exposes both CommonJS and ESM entrypoints. It also exports the
+raw generated Node-API module as `@bittensor/sdk/native`, so every native
+entry point is callable even when an ergonomic wrapper has not yet been
+added.
+
+## Build locally
+
+From the repository root:
+
+```sh
+cargo test -p bittensor-typescript-sdk-native --all-features
+npm --prefix sdk/typescript-sdk ci
+npm --prefix sdk/typescript-sdk run check
+```
+
+The native crate is isolated under `sdk/typescript-sdk/native`; it links
+`sdk/bittensor-core` directly and contains binding glue only. No chain
+algorithm is reimplemented in TypeScript.
+
+Node.js 20.17 or newer is required.
+
+## Example
+
+```ts
+import {
+  Keypair,
+  Runtime,
+  createKeyringPairFromUri,
+  sealMevShieldTransaction,
+} from '@bittensor/sdk'
+
+const alice = Keypair.fromUri('//Alice')
+const signature = alice.sign(Buffer.from('hello'))
+console.log(alice.verify(Buffer.from('hello'), signature))
+
+// Compatible with tx.signAsync(...) and Moonwall helpers, while the secret
+// key and signing operation remain in Rust.
+const signer = createKeyringPairFromUri('//Alice')
+
+const runtime = new Runtime(metadataBytes, specVersion, transactionVersion)
+const call = runtime.composeCall('System', 'remark', {
+  remark: Buffer.from('hello'),
+})
+
+const ciphertext = sealMevShieldTransaction(mlKemPublicKey, call)
+```
+
+Large SCALE integers are returned as `bigint`; byte carriers are returned as
+`Buffer`. A decoded SCALE dictionary with non-string keys is returned as a
+`Map`, so no key information is lost.

sdk/typescript-sdk/native/Cargo.toml

@@ -0,0 +1,29 @@
+[package]
+name = "bittensor-typescript-sdk-native"
+version = "0.1.0"
+edition = "2021"
+publish = false
+description = "Native Node-API bridge used by the Bittensor TypeScript SDK"
+license = "Apache-2.0"
+
+[lib]
+crate-type = ["cdylib"]
+
+[features]
+default = ["ledger"]
+ledger = ["bittensor-core/ledger"]
+
+[dependencies]
+bittensor-core = { path = "../../bittensor-core" }
+codec = { workspace = true }
+hex = "0.4.3"
+napi = { version = "3.10.3", default-features = false, features = ["napi8", "serde-json", "dyn-symbols"] }
+napi-derive = "3.5.9"
+scale-info = { workspace = true, features = ["std", "serde"] }
+serde_json = { version = "1.0.132", features = ["arbitrary_precision"] }
+
+[build-dependencies]
+napi-build = "2.3.2"
+
+[lints]
+workspace = true

sdk/typescript-sdk/native/build.rs

@@ -0,0 +1,3 @@
+fn main() {
+    napi_build::setup();
+}