rootchain-sdk 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RootChain
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,114 @@
+# rootchain-sdk
+
+<div align="center">
+  <h3>The Official TypeScript SDK for RootChain</h3>
+  <p>Communicate with RootChain nodes, deploy WASM smart contracts, and construct deterministic offline transactions seamlessly from any JavaScript environment.</p>
+
+  [![Version](https://img.shields.io/npm/v/rootchain-sdk.svg)](https://npmjs.org/package/rootchain-sdk)
+  [![TypeScript](https://img.shields.io/badge/Language-TypeScript-blue.svg)]()
+  [![License](https://img.shields.io/badge/License-MIT-green.svg)]()
+</div>
+
+---
+
+The `rootchain-sdk` provides a clean, heavily-typed API wrapper over the `rootchain-rpc` JSON-RPC 2.0 endpoints. It empowers developers to build rich, reactive Web3 interfaces on top of the RootChain ecosystem with absolute minimal overhead.
+
+## 📦 Installation
+
+This package is optimized for modern toolchains (Node >= 18, Bun, Vite).
+
+```bash
+npm install rootchain-sdk
+# or
+bun add rootchain-sdk
+# or
+yarn add rootchain-sdk
+# or
+pnpm add rootchain-sdk
+```
+
+## ⚡ Core Features
+
+*   **100% Type-Safe**: Comprehensive types for transactions, blocks, receipts, and RRC network structs.
+*   **Offline Transaction Building**: Deterministically serialize and sign payloads completely offline, mitigating key-leakage attacks.
+*   **JSON-RPC Provider Wrapper**: Native `JsonRpcProvider` for network data, account querying, and telemetry extraction.
+*   **Key Derivation**: Securely derive Ed25519 paths via standard BIP-39 mnemonic recovery phrases.
+*   **WASM Deployment Ready**: Methods and structures natively adapted for deploying and querying sandboxed webassembly bytecodes.
+
+## 🚀 Quick Start Guide
+
+### 1. Initialize the Provider
+
+Connect directly to your local node or remote `rootchain-rpc` endpoint:
+
+```typescript
+import { JsonRpcProvider } from 'rootchain-sdk';
+
+// Initialize the generic provider
+const provider = new JsonRpcProvider('http://localhost:8545');
+
+// Fetch network status
+const { height, chain_id } = await provider.getChainInfo();
+console.log(`Connected to ${chain_id} at block ${height}`);
+```
+
+### 2. Wallet & Account Derivation
+
+Derive your private keys deterministically and check your native balance securely:
+
+```typescript
+import { Wallet } from 'rootchain-sdk';
+
+// Instantiate a wallet connected to the provider
+const privateKeyHex = "0x4f3c..."; // Ensure 32-bytes representation
+const wallet = new Wallet(privateKeyHex, provider);
+
+// Resolve public key representation
+const address = await wallet.getAddress();
+
+// Retrieve canonical balance and account nonce
+const { balance, nonce } = await provider.getBalance(address);
+console.log(`Remaining Balance: ${balance} micro-ROOT`);
+```
+
+### 3. Issue a Raw Transaction
+
+Seamlessly instruct the provider to broadcast signed `Transfer` transitions directly to the PoA network:
+
+```typescript
+const txReceipt = await wallet.sendTransaction({
+  tx_type: "Transfer",
+  to: "0x8888...",          // 32-byte recipient Hash
+  amount: 1000000000000n,    // BigInt for safe u128 handling
+  fee: 1000n,                // Network execution fee
+  payload: new Uint8Array()  // Zero-length buffer for standardized transfers
+});
+
+console.log(`Transaction successfully queued with hash: ${txReceipt.hash}`);
+
+// Optionally, await network determinism
+await provider.waitForTransaction(txReceipt.hash);
+console.log('Transaction explicitly finalized within an immutable block!');
+```
+
+## 📚 Advanced Documentation
+
+### Submitting Equivocation Proofs
+The SDK provides a built-in helper for submitting proofs of validator misbehavior:
+
+```typescript
+const proof = {
+  validator: "0xaddr...",
+  height: 500,
+  round: 1,
+  hash_a: "0x...",
+  signature_a: "0x...",
+  hash_b: "0x...",
+  signature_b: "0x..."
+};
+
+const { hash } = await provider.submitEquivocationProof(proof);
+console.log(`Equivocation proof submitted: ${hash}`);
+```
+
+For deeper operational hooks into `rootchain-std` execution contracts (`ContractCall` and `ContractDeploy`), refer to the advanced ecosystem tutorials outlined in the `/docs` directory.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./provider.js";
+export * from "./signer.js";
+export * from "./wallet.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./provider.js";
+export * from "./signer.js";
+export * from "./wallet.js";

package/dist/provider.d.ts

@@ -0,0 +1,127 @@
+export interface ChainInfo {
+    height: number;
+    best_hash: string;
+    validators: string[];
+    slashed: string[];
+    chain_id: number;
+}
+export interface BalanceInfo {
+    balance: string;
+    nonce: number;
+}
+export interface Transaction {
+    tx_type: string;
+    from: number[] | string;
+    to: number[] | string;
+    amount: string;
+    fee: string;
+    nonce: number;
+    payload: number[] | string;
+    signature: number[] | string;
+}
+export interface ContractEvent {
+    contract_address: string;
+    topics: string[];
+    data: string;
+}
+export interface TransactionReceipt {
+    transaction: Transaction;
+    block_height: number;
+    block_hash: string;
+    events: ContractEvent[];
+    gas_used: string;
+    success: boolean;
+    error?: string;
+    transaction_hash?: string;
+}
+export interface EquivocationProof {
+    validator: string;
+    height: number;
+    round: number;
+    hash_a: string;
+    signature_a: string;
+    hash_b: string;
+    signature_b: string;
+}
+export interface Block {
+    header: {
+        height: number;
+        prev_hash: number[] | string;
+        merkle_root: number[] | string;
+        state_root: number[] | string;
+        proposer: number[] | string;
+        timestamp: number;
+        signature: number[] | string;
+    };
+    transactions: Transaction[];
+}
+export interface GovernanceProposal {
+    id: string;
+    type: string;
+    params: any;
+    status: 'Active' | 'Passed' | 'Failed';
+    signatures: number;
+    threshold: number;
+    description: string;
+    created_at: number;
+}
+export interface PeerInfo {
+    peer_id: string;
+    address: string;
+    rtt_ms: number;
+    height: number;
+}
+export interface ContractCode {
+    address: string;
+    bytecode: string;
+    bytecode_hex: string;
+}
+export interface StorageValue {
+    key: string;
+    value: string | null;
+}
+export declare class JsonRpcProvider {
+    readonly url: string;
+    constructor(url?: string);
+    send<T>(method: string, params?: any[]): Promise<T>;
+    getBalance(address: string): Promise<{
+        balance: string;
+        nonce: number;
+    }>;
+    sendRawTransaction(tx: any): Promise<{
+        hash: string;
+        contractAddress?: string;
+    }>;
+    getChainInfo(): Promise<ChainInfo>;
+    getFinalizedBlock(): Promise<Block | null>;
+    submitProposal(proposalHex: string, fromAddress: string, fee?: number): Promise<{
+        status: string;
+        tx_hash: string;
+    }>;
+    getGovernanceProposals(): Promise<GovernanceProposal[]>;
+    getPeerInfo(): Promise<PeerInfo[]>;
+    getCode(address: string): Promise<ContractCode>;
+    getStorageAt(address: string, key: string): Promise<StorageValue>;
+    getBlock(id: string | number): Promise<Block | null>;
+    getBlocks(endHeight?: number, limit?: number): Promise<Block[]>;
+    getTransaction(hash: string): Promise<TransactionReceipt | null>;
+    getTransactionsByAddress(address: string, limit?: number, offset?: number): Promise<TransactionReceipt[]>;
+    getLogs(filter: {
+        address?: string;
+        fromBlock?: number;
+        toBlock?: number;
+    }): Promise<any[]>;
+    submitEquivocationProof(proof: EquivocationProof): Promise<{
+        hash: string;
+    }>;
+    getMetadata(address: string): Promise<{
+        metadata: string;
+    } | null>;
+    waitForTransaction(hash: string, timeoutMs?: number): Promise<TransactionReceipt>;
+}
+export declare class EventDecoder {
+    /**
+     * Decodes a raw contract event using the contract's metadata schema.
+     */
+    static decode(event: ContractEvent, metadataJson: string | any): any;
+}

package/dist/provider.js

@@ -0,0 +1,131 @@
+export class JsonRpcProvider {
+    url;
+    constructor(url) {
+        // @ts-ignore
+        const envUrl = typeof process !== 'undefined' ? process.env.VITE_RPC_URL || process.env.RPC_URL : undefined;
+        // @ts-ignore
+        const metaUrl = typeof import.meta !== 'undefined' && import.meta.env ? import.meta.env.VITE_RPC_URL : undefined;
+        this.url = url || metaUrl || envUrl || 'http://127.0.0.1:8545';
+    }
+    async send(method, params = []) {
+        const response = await fetch(this.url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                jsonrpc: "2.0",
+                method,
+                params,
+                id: Date.now(),
+            }),
+        });
+        if (!response.ok) {
+            throw new Error(`HTTP Error: ${response.status}`);
+        }
+        const data = await response.json();
+        if (data.error) {
+            throw new Error(data.error.message);
+        }
+        return data.result;
+    }
+    async getBalance(address) {
+        return this.send("rootchain_getBalance", [address]);
+    }
+    async sendRawTransaction(tx) {
+        const result = await this.send("rootchain_sendRawTransaction", [tx]);
+        return {
+            hash: result.hash,
+            contractAddress: result.contractAddress || result.contract_address,
+        };
+    }
+    getChainInfo() {
+        return this.send('rootchain_getChainInfo');
+    }
+    getFinalizedBlock() {
+        return this.send('rootchain_getFinalizedBlock');
+    }
+    submitProposal(proposalHex, fromAddress, fee = 100) {
+        return this.send('rootchain_submitProposal', [proposalHex, fromAddress, fee]);
+    }
+    getGovernanceProposals() {
+        return this.send('rootchain_listProposals');
+    }
+    getPeerInfo() {
+        return this.send('rootchain_getNetworkTopology');
+    }
+    getCode(address) {
+        return this.send('rootchain_getCode', [address]);
+    }
+    getStorageAt(address, key) {
+        return this.send('rootchain_getStorageAt', [address, key]);
+    }
+    getBlock(id) {
+        return this.send('rootchain_getBlock', [id]);
+    }
+    async getBlocks(endHeight, limit = 20) {
+        // If no endHeight passed, first get the current chain height
+        if (endHeight === undefined) {
+            const info = await this.getChainInfo().catch(() => null);
+            endHeight = info?.height ?? 0;
+        }
+        return this.send('rootchain_getBlocks', [endHeight, limit]);
+    }
+    getTransaction(hash) {
+        return this.send('rootchain_getTransaction', [hash]);
+    }
+    getTransactionsByAddress(address, limit = 10, offset = 0) {
+        return this.send('rootchain_getTransactionsByAddress', [address, limit, offset]);
+    }
+    async getLogs(filter) {
+        return this.send("rootchain_getLogs", [filter]);
+    }
+    async submitEquivocationProof(proof) {
+        return this.send("rootchain_submitEquivocationProof", [proof]);
+    }
+    async getMetadata(address) {
+        return this.send('rootchain_getMetadata', [address]);
+    }
+    async waitForTransaction(hash, timeoutMs = 60000) {
+        const start = Date.now();
+        while (Date.now() - start < timeoutMs) {
+            const receipt = await this.getTransaction(hash);
+            if (receipt)
+                return receipt;
+            await new Promise(resolve => setTimeout(resolve, 1000));
+        }
+        throw new Error(`Timeout waiting for transaction ${hash}`);
+    }
+}
+export class EventDecoder {
+    /**
+     * Decodes a raw contract event using the contract's metadata schema.
+     */
+    static decode(event, metadataJson) {
+        try {
+            const metadata = typeof metadataJson === 'string' ? JSON.parse(metadataJson) : metadataJson;
+            if (!metadata || !metadata.events)
+                return event;
+            // Simple matching: find event with same number of topics
+            for (const [name, schema] of Object.entries(metadata.events)) {
+                const s = schema;
+                if (event.topics.length === s.topics.length) {
+                    const params = {};
+                    s.topics.forEach((topicName, i) => {
+                        params[topicName] = event.topics[i];
+                    });
+                    if (s.data) {
+                        params[s.data] = event.data;
+                    }
+                    return {
+                        name,
+                        address: event.contract_address,
+                        parameters: params
+                    };
+                }
+            }
+        }
+        catch (e) {
+            console.error("Failed to decode event:", e);
+        }
+        return event;
+    }
+}

package/dist/signer.d.ts

@@ -0,0 +1,19 @@
+import type { JsonRpcProvider } from "./provider.js";
+export interface TransactionRequest {
+    tx_type: string;
+    from?: string;
+    to?: string;
+    amount?: bigint | string | number;
+    fee?: bigint | string | number;
+    nonce?: number;
+    payload?: Uint8Array;
+}
+export interface Signer {
+    getAddress(): Promise<string>;
+    signTransaction(tx: TransactionRequest): Promise<string>;
+    sendTransaction(tx: TransactionRequest): Promise<{
+        hash: string;
+        contractAddress?: string;
+    }>;
+    connect(provider: JsonRpcProvider): Signer;
+}

package/dist/signer.js

@@ -0,0 +1 @@
+export {};

package/dist/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["../src/index.ts","../src/provider.ts","../src/signer.ts","../src/wallet.ts"],"version":"5.9.3"}

package/dist/wallet.d.ts

@@ -0,0 +1,17 @@
+import type { JsonRpcProvider } from "./provider.js";
+import type { Signer, TransactionRequest } from "./signer.js";
+export declare class Wallet implements Signer {
+    private address?;
+    readonly privateKeyHex: string;
+    readonly provider?: JsonRpcProvider;
+    constructor(privateKeyHex: string, provider?: JsonRpcProvider);
+    connect(provider: JsonRpcProvider): Wallet;
+    getAddress(): Promise<string>;
+    getContractAddress(nonce: number): Promise<string>;
+    signTransaction(tx: TransactionRequest): Promise<string>;
+    sendTransaction(tx: TransactionRequest): Promise<{
+        hash: string;
+        contractAddress?: string;
+    }>;
+    private hexToBytes;
+}

package/dist/wallet.js

@@ -0,0 +1,69 @@
+import { get_address_from_key, sign_transaction, get_contract_address } from "rootchain-wasm";
+export class Wallet {
+    address;
+    privateKeyHex;
+    provider;
+    constructor(privateKeyHex, provider) {
+        this.privateKeyHex = privateKeyHex;
+        this.provider = provider;
+    }
+    connect(provider) {
+        return new Wallet(this.privateKeyHex, provider);
+    }
+    async getAddress() {
+        if (this.address)
+            return this.address;
+        const cleanKey = this.privateKeyHex.replace("0x", "");
+        const result = get_address_from_key(cleanKey);
+        this.address = typeof result === "string" ? result : result.toString();
+        return this.address;
+    }
+    async getContractAddress(nonce) {
+        const address = await this.getAddress();
+        return get_contract_address(address, BigInt(nonce));
+    }
+    async signTransaction(tx) {
+        // Fill missing fields
+        const fullTx = {
+            tx_type: tx.tx_type,
+            from: Array(32).fill(0), // WASM overwrites this anyway based on private key
+            to: tx.to ? this.hexToBytes(tx.to) : Array(32).fill(0),
+            amount: tx.amount?.toString() ?? "0",
+            fee: tx.fee?.toString() ?? "1000",
+            nonce: tx.nonce ?? 1,
+            payload: tx.payload ? Array.from(tx.payload) : [],
+            signature: Array(64).fill(0)
+        };
+        const cleanKey = this.privateKeyHex.replace("0x", "");
+        return sign_transaction(JSON.stringify(fullTx), cleanKey);
+    }
+    async sendTransaction(tx) {
+        if (!this.provider) {
+            throw new Error("Wallet is not connected to a Provider");
+        }
+        const address = await this.getAddress();
+        // Auto-fetch nonce if not provided
+        if (tx.nonce === undefined) {
+            const { nonce } = await this.provider.getBalance(address);
+            tx.nonce = nonce + 1; // Expected nonce is current recorded nonce + 1
+        }
+        let predictedAddress;
+        if (tx.tx_type === "ContractDeploy") {
+            predictedAddress = await this.getContractAddress(tx.nonce);
+        }
+        const signedTxJson = await this.signTransaction(tx);
+        const result = await this.provider.sendRawTransaction(JSON.parse(signedTxJson));
+        return {
+            hash: result.hash,
+            contractAddress: result.contractAddress || predictedAddress
+        };
+    }
+    hexToBytes(hex) {
+        const cleanHex = hex.replace("0x", "");
+        const bytes = new Uint8Array(cleanHex.length / 2);
+        for (let i = 0; i < cleanHex.length; i += 2) {
+            bytes[i / 2] = parseInt(cleanHex.substring(i, i + 2), 16);
+        }
+        return Array.from(bytes);
+    }
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "rootchain-sdk",
+  "version": "1.0.1",
+  "description": "The Official TypeScript SDK for RootChain - High-precision RPC client.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BronzonTech-Cloud/rootchain.git"
+  },
+  "keywords": [
+    "rootchain",
+    "blockchain",
+    "sdk",
+    "u128",
+    "wasm",
+    "wallet"
+  ],
+  "author": "Charles Bronzon",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/BronzonTech-Cloud/rootchain/issues"
+  },
+  "homepage": "https://github.com/BronzonTech-Cloud/rootchain#readme",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "rootchain-wasm": "^1.0.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}