@d9-network/spec 0.0.1

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@d9-network/spec",
+  "version": "0.0.1",
+  "private": false,
+  "author": {
+    "email": "jgbingzi@outlook.com",
+    "name": "Cyenoch",
+    "url": "https://github.com/Cyenoch"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "publishConfig": {
+    "exports": {
+      ".": {
+        "require": "./dist/index.cjs",
+        "import": "./dist/index.mjs"
+      },
+      "./package.json": "./package.json"
+    },
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "test": "bun test",
+    "build": "papi && tsdown",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@d9-network/ink": "0.0.1",
+    "@polkadot-labs/hdkd": "^0.0.11",
+    "@polkadot-labs/hdkd-helpers": "^0.0.11",
+    "@polkadot-api/descriptors": "file:.papi/descriptors",
+    "@polkadot-api/legacy-provider": "^0.3.6",
+    "@polkadot-api/signer": "^0.2.11",
+    "@polkadot-api/substrate-bindings": "^0.16.5",
+    "polkadot-api": "^1.23.1",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "latest",
+    "tsdown": "^0.18.1",
+    "typescript": "~5.9.3"
+  }
+}

package/scripts/papi-add-ink.ts

@@ -0,0 +1,104 @@
+#!/usr/bin/env bun
+
+import { Glob } from "bun";
+
+/**
+ * Script to add all JSON files from assets/ABIs directory using papi ink add
+ */
+
+const SCRIPT_DIR = import.meta.dir!;
+const SDK_DIR = `${SCRIPT_DIR}/..`;
+
+/**
+ * Convert filename to camelCase key
+ * Examples:
+ * - "d9-usdt.json" -> "d9Usdt"
+ * - "burn-manager.json" -> "burnManager"
+ * - "cross_chain_transfer.json" -> "crossChainTransfer"
+ * - "node_reward.json" -> "nodeReward"
+ */
+function toCamelCase(filename: string): string {
+  // Remove .json extension
+  const name = filename.replace(/\.json$/, "");
+  
+  // Split by hyphens, underscores, or camelCase boundaries
+  const parts = name.split(/[-_]/);
+  
+  // Convert to camelCase
+  return parts
+    .map((part, index) => {
+      if (index === 0) {
+        // Keep first part as-is (could be lowercase or have numbers)
+        return part;
+      }
+      // Capitalize first letter of subsequent parts
+      return part.charAt(0).toUpperCase() + part.slice(1).toLowerCase();
+    })
+    .join("");
+}
+
+async function main() {
+  try {
+    // Use Bun Glob to find all JSON files in assets/ABIs directory
+    const glob = new Glob("assets/ABIs/*.json");
+    const jsonFiles: string[] = [];
+
+    for await (const file of glob.scan({
+      cwd: SDK_DIR,
+    })) {
+      jsonFiles.push(file);
+    }
+
+    if (jsonFiles.length === 0) {
+      console.log("No JSON files found in assets/ABIs directory");
+      return;
+    }
+
+    console.log(`Found ${jsonFiles.length} JSON file(s) to process:\n`);
+    jsonFiles.forEach((file: string) => console.log(`  - ${file}`));
+    console.log();
+
+    // Process each JSON file
+    for (const file of jsonFiles) {
+      const fileName = file.split("/").pop() || file;
+      const camelKey = toCamelCase(fileName);
+      console.log(`Processing: ${fileName} (key: ${camelKey})`);
+
+      try {
+        // Execute papi ink add command with -k parameter using Bun.$ from SDK directory
+        const result = await Bun.$`bun papi ink add ${file} -k ${camelKey} --skip-codegen`.cwd(SDK_DIR);
+
+        if (result.exitCode === 0) {
+          console.log(`✓ Successfully added: ${fileName}`);
+          const output = result.stdout.toString().trim();
+          if (output) {
+            console.log(`  ${output}`);
+          }
+          console.log();
+        } else {
+          console.error(`✗ Failed to add: ${fileName}`);
+          const errorOutput = result.stderr.toString().trim();
+          if (errorOutput) {
+            console.error(`  ${errorOutput}`);
+          }
+          const stdoutOutput = result.stdout.toString().trim();
+          if (stdoutOutput) {
+            console.error(`  ${stdoutOutput}`);
+          }
+          console.log();
+        }
+      } catch (error) {
+        console.error(`✗ Error processing ${fileName}:`, error);
+        console.log();
+      }
+    }
+
+    Bun.$`bun papi`.cwd(SDK_DIR);
+    console.log("Done!");
+  } catch (error) {
+    console.error("Error processing files:", error);
+    process.exit(1);
+  }
+}
+
+main();

package/src/client.ts

@@ -0,0 +1,68 @@
+import { d9, getMetadata } from "@polkadot-api/descriptors";
+import { createClient, type CreateClientOptions } from "polkadot-api";
+import { getWsProvider } from "polkadot-api/ws-provider";
+import { withPolkadotSdkCompat } from "polkadot-api/polkadot-sdk-compat";
+import { withLegacy } from "@polkadot-api/legacy-provider";
+import { createD9InkSdk } from "@d9-network/ink";
+
+export type CreateD9SdkClientOptions = {
+  endpoint: string;
+  wsProvider?: Parameters<typeof getWsProvider>[1];
+  metadata?: CreateClientOptions;
+};
+
+/**
+ * Create a D9 SDK client with ink contract support.
+ *
+ * This client uses state_call + ContractsApi_call for contract interactions
+ * instead of ReviveApi, which is not supported on the D9 chain.
+ *
+ * @example
+ * ```ts
+ * const d9Client = createD9SdkClient({
+ *   endpoint: "wss://mainnet.d9network.com:40300",
+ * });
+ *
+ * // Query USDT balance
+ * const result = await d9Client.contracts.usdt.query("PSP22::balance_of", {
+ *   origin: aliceAddress,
+ *   args: { owner: aliceAddress },
+ * });
+ *
+ * if (result.success) {
+ *   console.log("Balance:", result.value.response);
+ * }
+ * ```
+ */
+export function createD9SdkClient(options: CreateD9SdkClientOptions) {
+  const provider = getWsProvider(options.endpoint, {
+    innerEnhancer: withLegacy(),
+    ...options.wsProvider,
+  });
+
+  const client = createClient(withPolkadotSdkCompat(provider), {
+    ...options.metadata,
+    async getMetadata(codeHash) {
+      // Prefer upstream metadata if present, otherwise fallback to embedded descriptors metadata.
+      const custom = options.metadata?.getMetadata
+        ? await options.metadata.getMetadata(codeHash)
+        : null;
+      if (custom) return custom;
+      const metadata = await getMetadata(codeHash);
+      return metadata ?? null;
+    },
+  });
+
+  const api = client.getTypedApi(d9);
+
+  // Create D9 Ink SDK with typedApi for transaction support
+  const inkSdk = createD9InkSdk(client, { typedApi: api });
+
+  return {
+    client,
+    api,
+    inkSdk,
+  };
+}
+
+export type D9SdkClientReturn = ReturnType<typeof createD9SdkClient>;

package/src/index.ts

@@ -0,0 +1,17 @@
+export * from "./client";
+export * from "./wallet";
+export * from "@polkadot-api/descriptors";
+
+// Re-export @d9-network/ink types and functions for use in @d9-network/app
+export {
+	createPSP22TransferStream,
+	createNativeTransferStream,
+	createContractEventStream,
+	ContractEventParser,
+} from "@d9-network/ink";
+export type {
+	DecodedContractEvent,
+	RawContractEvent,
+	EventSubscriptionOptions,
+	EventFilterOptions,
+} from "@d9-network/ink";

package/src/wallet/account.ts

@@ -0,0 +1,57 @@
+import type { SS58String } from "polkadot-api";
+
+import { mnemonicToMiniSecret } from "./mnemonic";
+import { hexToBytes, type HexString } from "./hex";
+import {
+  sr25519DeriveFromMiniSecret,
+  sr25519KeypairFromMiniSecret,
+  sr25519AddressFromKeypair,
+} from "./sr25519";
+import {
+  createSr25519SignerFromKeypair,
+} from "./signer";
+
+export type WalletAccount = {
+  address: SS58String;
+  publicKey: Uint8Array;
+  /**
+   * Signer for polkadot-api transactions
+   */
+  signer: ReturnType<typeof createSr25519SignerFromKeypair>;
+};
+
+export function createAccountFromMnemonic(options: {
+  mnemonic: string;
+  ss58Format?: number;
+  password?: string;
+  derivationPath?: string;
+  keyType?: "sr25519" | "ed25519" | "secp256k1";
+}): WalletAccount {
+  const miniSecret = mnemonicToMiniSecret(options.mnemonic, options.password);
+  const keypair = options.derivationPath
+    ? sr25519DeriveFromMiniSecret(miniSecret, options.derivationPath)
+    : sr25519KeypairFromMiniSecret(miniSecret);
+
+  return {
+    address: sr25519AddressFromKeypair(keypair, options.ss58Format),
+    publicKey: keypair.publicKey,
+    signer: createSr25519SignerFromKeypair(keypair),
+  };
+}
+
+export function createAccountFromPrivateKey(options: {
+  secretKeyHex: HexString;
+  ss58Format?: number;
+  keyType: "sr25519" | "ed25519" | "secp256k1";
+}): WalletAccount {
+  const secretBytes = hexToBytes(options.secretKeyHex);
+  if (secretBytes.length !== 32) {
+    throw new Error("secret key must be 32 bytes");
+  }
+  const keypair = sr25519KeypairFromMiniSecret(secretBytes);
+  return {
+    address: sr25519AddressFromKeypair(keypair, options.ss58Format),
+    publicKey: keypair.publicKey,
+    signer: createSr25519SignerFromKeypair(keypair),
+  };
+}

package/src/wallet/hex.ts

@@ -0,0 +1,30 @@
+import type { HexString } from "polkadot-api";
+
+export type { HexString } from "polkadot-api";
+
+export function isHexString(input: unknown): input is HexString {
+  if (typeof input !== "string") return false;
+  if (!input.startsWith("0x")) return false;
+  const s = input.slice(2);
+  return s.length % 2 === 0 && /^[0-9a-fA-F]+$/.test(s);
+}
+
+export function hexToBytes(hex: unknown): Uint8Array {
+  if (!isHexString(hex)) {
+    throw new Error("Invalid hex string");
+  }
+  const s = (hex as string).slice(2);
+  const out = new Uint8Array(s.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    out[i] = Number.parseInt(s.slice(i * 2, i * 2 + 2), 16);
+  }
+  return out;
+}
+
+export function bytesToHex(bytes: Uint8Array): HexString {
+  let hex = "";
+  for (let i = 0; i < bytes.length; i++) {
+    hex += bytes[i]!.toString(16).padStart(2, "0");
+  }
+  return `0x${hex}` as const;
+}

package/src/wallet/index.ts

@@ -0,0 +1,6 @@
+export * from "./hex";
+export * from "./mnemonic";
+export * from "./ss58";
+export * from "./sr25519";
+export * from "./signer";
+export * from "./account";

package/src/wallet/mnemonic.ts

@@ -0,0 +1,19 @@
+import {
+  generateMnemonic as hdkdGenerateMnemonic,
+  mnemonicToMiniSecret as hdkdMnemonicToMiniSecret,
+  validateMnemonic as hdkdValidateMnemonic,
+} from "@polkadot-labs/hdkd-helpers";
+
+export function generateMnemonic(): string {
+  return hdkdGenerateMnemonic();
+}
+
+export function validateMnemonic(mnemonic: string): boolean {
+  return hdkdValidateMnemonic(mnemonic);
+}
+
+export function mnemonicToMiniSecret(mnemonic: string, password?: string): Uint8Array {
+  if (!validateMnemonic(mnemonic)) throw new Error("Invalid mnemonic");
+  return hdkdMnemonicToMiniSecret(mnemonic, password);
+}
+

package/src/wallet/signer.ts

@@ -0,0 +1,9 @@
+import { getPolkadotSigner } from "@polkadot-api/signer";
+import type { PolkadotSigner } from "polkadot-api";
+import type { KeyPair } from "@polkadot-labs/hdkd-helpers";
+
+export type { PolkadotSigner } from "polkadot-api";
+
+export function createSr25519SignerFromKeypair(keypair: KeyPair): PolkadotSigner {
+  return getPolkadotSigner(keypair.publicKey, "Sr25519", (payload) => keypair.sign(payload));
+}

package/src/wallet/sr25519.ts

@@ -0,0 +1,42 @@
+import { sr25519CreateDerive, withNetworkAccount } from "@polkadot-labs/hdkd";
+import type { KeyPair } from "@polkadot-labs/hdkd-helpers";
+import type { SS58String } from "polkadot-api";
+
+import { hexToBytes } from "./hex";
+
+export type Sr25519Keypair = KeyPair;
+
+export function sr25519KeypairFromMiniSecret(miniSecret: Uint8Array): Sr25519Keypair {
+  const derive = sr25519CreateDerive(miniSecret);
+  const kp = derive("");
+  // hdkd derives at the root when path is empty string.
+  return kp;
+}
+
+export function sr25519DeriveFromMiniSecret(
+  miniSecret: Uint8Array,
+  derivationPath: string,
+): Sr25519Keypair {
+  const derive = sr25519CreateDerive(miniSecret);
+  return derive(derivationPath);
+}
+
+export function sr25519AddressFromKeypair(
+  keypair: Sr25519Keypair,
+  ss58Format?: number,
+): SS58String {
+  return withNetworkAccount(keypair, ss58Format).ss58Address as SS58String;
+}
+
+export function sr25519AddressFromSecretKeyHex(
+  secretKeyHex: string,
+  ss58Format: number,
+): SS58String {
+  const secretKey = hexToBytes(secretKeyHex);
+  if (secretKey.length !== 32) {
+    throw new Error("sr25519 secret key must be 32 bytes");
+  }
+  const keypair = sr25519KeypairFromMiniSecret(secretKey);
+  return sr25519AddressFromKeypair(keypair, ss58Format);
+}
+

package/src/wallet/ss58.ts

@@ -0,0 +1,14 @@
+import { ss58Decode, ss58Encode } from "@polkadot-labs/hdkd-helpers";
+import type { SS58String } from "polkadot-api";
+
+export type { SS58String } from "polkadot-api";
+
+export function ss58DecodePublicKey(address: SS58String): Uint8Array {
+  const [publicKey] = ss58Decode(address);
+  return publicKey;
+}
+
+export function ss58Reencode(address: SS58String, ss58Format: number): SS58String {
+  const publicKey = ss58DecodePublicKey(address);
+  return ss58Encode(publicKey, ss58Format) as SS58String;
+}

package/test/client.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from "bun:test";
+
+import { createD9SdkClient } from "../src";
+
+describe("client factory", () => {
+  it("creates client with api and inkSdk", () => {
+    const sdk = createD9SdkClient({ endpoint: "ws://127.0.0.1:0" });
+
+    expect(sdk.client).toBeDefined();
+    expect(sdk.api).toBeDefined();
+    expect(typeof sdk.inkSdk.getContract).toBe("function");
+
+    sdk.client.destroy();
+  });
+});

package/test/descriptors.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "bun:test";
+
+import { contracts, getMetadata } from "../src";
+
+describe("descriptors exports", () => {
+  it("exposes contract metadata and metadata lookup", async () => {
+    const descriptor = contracts.usdt;
+    expect(descriptor).toBeDefined();
+
+    expect(descriptor.metadata).toBeDefined();
+    const hash = descriptor.metadata?.source?.hash;
+    if (!hash) {
+      throw new Error("contracts.usdt.metadata.source.hash is missing");
+    }
+    expect(hash.startsWith("0x")).toBe(true);
+
+    const metadata = await getMetadata(hash);
+    expect(metadata).toBeNull();
+
+    const configUrl = new URL("../.papi/polkadot-api.json", import.meta.url);
+    const configText = await Bun.file(configUrl).text();
+    const config = JSON.parse(configText) as {
+      entries?: Record<string, { codeHash?: string }>;
+    };
+    const chainHash = config.entries?.d9?.codeHash;
+    expect(chainHash).toBeDefined();
+    if (chainHash) {
+      const chainMetadata = await getMetadata(chainHash);
+      expect(chainMetadata).not.toBeNull();
+    }
+  });
+});

package/test/wallet.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from "bun:test";
+
+import { DEV_MINI_SECRET, DEV_PHRASE } from "@polkadot-labs/hdkd-helpers";
+import {
+  createAccountFromMnemonic,
+  createAccountFromPrivateKey,
+  mnemonicToMiniSecret,
+  sr25519AddressFromKeypair,
+  sr25519DeriveFromMiniSecret,
+  sr25519KeypairFromMiniSecret,
+} from "../src/wallet/index";
+import { createSr25519SignerFromKeypair } from "../src/wallet/signer";
+
+const DEV_SS58_FORMAT = 9;
+
+describe("wallet sr25519 account + signer", () => {
+  it("exposes publicKey in PolkadotSigner", () => {
+    const seed = Uint8Array.from(Buffer.from(DEV_MINI_SECRET, "hex"));
+    const keypair = sr25519KeypairFromMiniSecret(seed);
+    const signer = createSr25519SignerFromKeypair(keypair);
+
+    expect(Buffer.from(signer.publicKey).toString("hex")).toBe(
+      Buffer.from(keypair.publicKey).toString("hex"),
+    );
+  });
+
+  it("createAccountFromMnemonic uses same address as raw keypair", () => {
+    const miniSecret = mnemonicToMiniSecret(DEV_PHRASE);
+    const keypair = sr25519KeypairFromMiniSecret(miniSecret);
+    const expectedAddress = sr25519AddressFromKeypair(keypair, DEV_SS58_FORMAT);
+    const account = createAccountFromMnemonic({
+      mnemonic: DEV_PHRASE,
+      keyType: "sr25519",
+      ss58Format: DEV_SS58_FORMAT,
+    });
+
+    expect(account.address).toBe(expectedAddress);
+  });
+
+  it("supports derivation paths", () => {
+    const miniSecret = mnemonicToMiniSecret(DEV_PHRASE);
+    const derived = sr25519DeriveFromMiniSecret(miniSecret, "//test");
+    const expectedAddress = sr25519AddressFromKeypair(derived, DEV_SS58_FORMAT);
+    const account = createAccountFromMnemonic({
+      mnemonic: DEV_PHRASE,
+      keyType: "sr25519",
+      derivationPath: "//test",
+      ss58Format: DEV_SS58_FORMAT,
+    });
+
+    expect(account.address).toBe(expectedAddress);
+  });
+});
+
+describe("wallet secret key validation", () => {
+  it("throws when secret key is not 32 bytes", () => {
+    expect(() =>
+      createAccountFromPrivateKey({
+        secretKeyHex: "0x1234",
+        keyType: "sr25519",
+        ss58Format: DEV_SS58_FORMAT,
+      }),
+    ).toThrow("secret key must be 32 bytes");
+  });
+});

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "noEmit": true,
+    "types": ["bun"],
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*", "test/**/*", "scripts/**/*"]
+}
+

package/tsdown.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from "tsdown"
+
+export default defineConfig({
+  entry: ["./src/index.ts"],
+  outDir: "./dist",
+  format: ["esm", "cjs"],
+  sourcemap: true,
+  clean: true,
+  dts: true,
+  exports: {
+    devExports: true
+  },
+})