shell-sdk 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## [0.2.0] — 2026-04-14
+## [0.3.0] — 2026-04-22
 
 ### Added
 - **API freeze**: `ShellSigner`, `ShellProvider`, and `ShellWallet` are now stable public APIs.
@@ -8,18 +8,13 @@
 - `examples/minimal-dapp`: Node.js (`node-demo.mjs`) and browser (`browser-demo.html`) integration examples.
 - JSDoc complete for all public-facing exports.
 - `MlDsa65Adapter` round-trip sign+verify test.
+- `getNodeInfo()`, `getWitness()`, and `getStorageProfile()` helpers for Shell-specific node capabilities.
 
 ### Changed
 - `adapters.ts`: both `"Dilithium3"` and `"MlDsa65"` aliases now explicitly document ML-DSA-65 (FIPS 204) wire compatibility with the chain's Dilithium3 verifier.
 - `hashTransaction()` canonical RLP field ordering aligned with `shell-chain` deserialiser.
 - Package root export surface narrowed to stable application-facing APIs.
-
-
-
-- **Signing compatibility confirmed**: `pqcrypto-dilithium` v0.5 (shell-chain) implements FIPS 204 ML-DSA-65, byte-identical with `@noble/post-quantum` `ml_dsa65`. The `Dilithium3` alias in the SDK now documents this equivalence explicitly (pk=1952, sk=4032, sig=3309 bytes).
-- add cross-validation tests verifying ML-DSA-65 key/signature sizes against chain expectations
-- add `MlDsa65Adapter` round-trip sign+verify test
-- clarify `adapters.ts` JSDoc: both `"Dilithium3"` and `"MlDsa65"` route to ML-DSA-65 (FIPS 204) which is wire-compatible with the chain's Dilithium3 verifier
+- NodeInfo example version string now reflects current node naming (`shell-node/0.17.0`) without tying the SDK package version to the chain version.
 
 ## 0.2.0-rc.1
 

package/README.md

@@ -1,6 +1,6 @@
 # shell-sdk
 
-**TypeScript / JavaScript SDK for Shell Chain** — a post-quantum blockchain with native account abstraction.
+**TypeScript / JavaScript SDK for Shell Chain** — build quantum-safe dApps on the first EVM chain secured before Q-Day.
 
 [![Node ≥ 18](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org/)
 [![ESM only](https://img.shields.io/badge/module-ESM-blue)](https://nodejs.org/api/esm.html)
@@ -39,7 +39,8 @@
 - **PQ addresses** — bech32m-encoded `pq1…` addresses derived from PQ public keys via BLAKE3
 - **Native account abstraction** — key rotation and custom validation code via system contracts
 - **viem integration** — standard Ethereum JSON-RPC methods via a typed `PublicClient`
-- **Shell-specific RPC** — `shell_getPqPubkey`, `shell_sendTransaction`, `shell_getTransactionsByAddress`
+- **Shell-specific RPC** — `shell_getPqPubkey`, `shell_sendTransaction`, `shell_getTransactionsByAddress`, `shell_getNodeInfo`, `shell_getWitness`
+- **Node introspection** — `getNodeInfo()` returns version, block height, peer count, and storage profile; `getWitness()` fetches raw PQ signatures for any block
 - **Encrypted keystore** — argon2id KDF + xchacha20-poly1305 cipher; compatible with the Shell CLI
 
 ---
@@ -237,6 +238,9 @@ import { shellDevnet } from "shell-sdk/provider";
 | `sendTransaction(signed)` | `shell_sendTransaction` → tx hash string |
 | `getTransactionsByAddress(address, opts)` | `shell_getTransactionsByAddress` with optional `fromBlock/toBlock/page/limit` |
 | `getBlockReceipts(block)` | `eth_getBlockReceipts` → array of receipts |
+| `getNodeInfo()` | `shell_getNodeInfo` → `ShellNodeInfo` (version, block height, peer count, storage profile) |
+| `getWitness(blockNumberOrHash)` | `shell_getWitness` → `ShellWitnessBundle` or `null` if pruned |
+| `getStorageProfile()` | Convenience wrapper around `getNodeInfo()` → `ShellStorageProfile \| undefined` |
 
 **Examples:**
 

package/dist/index.d.ts

@@ -5,4 +5,4 @@ export { buildClearValidationCodeTransaction, buildRotateKeyTransaction, buildSe
 export { assertSignerMatchesKeystore, decryptKeystore, exportEncryptedKeyJson, parseEncryptedKey, validateEncryptedKeyAddress, type ParsedShellKeystore, } from "./keystore.js";
 export { adapterFromKeyPair, generateAdapter, generateMlDsa65KeyPair, generateSlhDsaKeyPair, MlDsa65Adapter, SlhDsaAdapter, type MlDsa65KeyPair, type SlhDsaKeyPair, } from "./adapters.js";
 export { buildShellSignature, publicKeyFromHex, ShellSigner, signatureTypeFromKeyType, type SignerAdapter, } from "./signer.js";
-export type { AddressLike, HexString, ShellAccessListItem, ShellCipherParams, ShellEncryptedKey, ShellSendTransactionParams, ShellKdfParams, ShellSignature, ShellTransactionRequest, ShellTxByAddressPage, SignedShellTransaction, SignatureTypeName, } from "./types.js";
+export type { AddressLike, HexString, ShellAccessListItem, ShellCipherParams, ShellEncryptedKey, ShellNodeInfo, ShellSendTransactionParams, ShellKdfParams, ShellSignature, ShellStorageProfile, ShellTransactionRequest, ShellTxByAddressPage, ShellTxWitness, ShellWitnessBundle, SignedShellTransaction, SignatureTypeName, } from "./types.js";

package/dist/provider.d.ts

@@ -16,7 +16,7 @@
  * @module provider
  */
 import { type Chain, type PublicClient } from "viem";
-import type { SignedShellTransaction } from "./types.js";
+import type { ShellNodeInfo, ShellStorageProfile, ShellWitnessBundle, SignedShellTransaction } from "./types.js";
 /**
  * Pre-configured viem chain definition for Shell Devnet.
  *
@@ -155,6 +155,34 @@ export declare class ShellProvider {
      * @returns Array of transaction receipt objects.
      */
     getBlockReceipts(block: string): Promise<unknown[]>;
+    /**
+     * Fetch metadata about the connected Shell Chain node.
+     *
+     * Calls `shell_getNodeInfo`.
+     *
+     * @returns Node info including version, block height, peer count, and storage profile.
+     */
+    getNodeInfo(): Promise<ShellNodeInfo>;
+    /**
+     * Fetch the PQ witness bundle for a block.
+     *
+     * Calls `shell_getWitness`. Returns `null` if the witness has been pruned
+     * (the node is running with a `full` or `light` profile and the STARK proof
+     * has already replaced the raw signatures).
+     *
+     * @param blockNumberOrHash - Hex block number (`"0x1a"`) or block hash.
+     * @returns Witness bundle, or `null` if pruned.
+     */
+    getWitness(blockNumberOrHash: string): Promise<ShellWitnessBundle | null>;
+    /**
+     * Fetch the active storage profile of the connected node.
+     *
+     * Convenience wrapper around {@link getNodeInfo}.
+     *
+     * @returns Storage profile string (`"archive"`, `"full"`, or `"light"`), or
+     *   `undefined` if the node does not report it.
+     */
+    getStorageProfile(): Promise<ShellStorageProfile | undefined>;
 }
 /**
  * Create a viem `PublicClient` connected to Shell Chain over HTTP.

package/dist/provider.js

@@ -137,6 +137,41 @@ export class ShellProvider {
     async getBlockReceipts(block) {
         return this.request("eth_getBlockReceipts", [block]);
     }
+    /**
+     * Fetch metadata about the connected Shell Chain node.
+     *
+     * Calls `shell_getNodeInfo`.
+     *
+     * @returns Node info including version, block height, peer count, and storage profile.
+     */
+    async getNodeInfo() {
+        return this.request("shell_getNodeInfo", []);
+    }
+    /**
+     * Fetch the PQ witness bundle for a block.
+     *
+     * Calls `shell_getWitness`. Returns `null` if the witness has been pruned
+     * (the node is running with a `full` or `light` profile and the STARK proof
+     * has already replaced the raw signatures).
+     *
+     * @param blockNumberOrHash - Hex block number (`"0x1a"`) or block hash.
+     * @returns Witness bundle, or `null` if pruned.
+     */
+    async getWitness(blockNumberOrHash) {
+        return this.request("shell_getWitness", [blockNumberOrHash]);
+    }
+    /**
+     * Fetch the active storage profile of the connected node.
+     *
+     * Convenience wrapper around {@link getNodeInfo}.
+     *
+     * @returns Storage profile string (`"archive"`, `"full"`, or `"light"`), or
+     *   `undefined` if the node does not report it.
+     */
+    async getStorageProfile() {
+        const info = await this.getNodeInfo();
+        return info.storage_profile;
+    }
 }
 /**
  * Create a viem `PublicClient` connected to Shell Chain over HTTP.

package/dist/types.d.ts

@@ -82,6 +82,61 @@ export interface SignedShellTransaction {
      */
     sender_pubkey?: number[] | null;
 }
+/**
+ * Node storage profile as advertised via the `StorageCapability` P2P message.
+ *
+ * - `"archive"` — all TX bodies and PQ witnesses kept forever; STARK proofs never replace witnesses.
+ * - `"full"` — TX bodies kept forever; PQ witnesses replaced by STARK proofs when they arrive.
+ * - `"light"` — rolling ~4096-block window; older data pruned.
+ */
+export type ShellStorageProfile = "archive" | "full" | "light";
+/**
+ * Response from `shell_getNodeInfo`.
+ *
+ * Contains runtime metadata about the connected Shell Chain node.
+ */
+export interface ShellNodeInfo {
+    /** Node software version string, e.g. `"shell-node/0.17.0"`, independent of the SDK package version. */
+    version: string;
+    /** Chain ID as a decimal string. */
+    chain_id: string;
+    /** Current head block number (decimal). */
+    block_height: number;
+    /** libp2p peer ID of this node. */
+    peer_id: string;
+    /** Number of currently connected peers. */
+    peer_count: number;
+    /** Active storage profile. */
+    storage_profile?: ShellStorageProfile;
+    /** Oldest block number for which this node has full body data. */
+    oldest_body_block?: number;
+}
+/**
+ * A single PQ transaction witness from `shell_getBlockWitnesses` / `shell_getWitness`.
+ */
+export interface ShellTxWitness {
+    /** Zero-based transaction index within the block. */
+    tx_index: number;
+    /** Signature algorithm name. */
+    sig_type: SignatureTypeName;
+    /** Raw signature bytes as hex string. */
+    signature: string;
+    /** Raw public key bytes as hex string (only present on first-use txs). */
+    public_key?: string;
+}
+/**
+ * Response from `shell_getWitness` for a single block.
+ */
+export interface ShellWitnessBundle {
+    /** Block hash (0x-prefixed). */
+    block_hash: string;
+    /** Block number. */
+    block_number: number;
+    /** Number of witnesses in this bundle. */
+    witness_count: number;
+    /** Individual transaction witnesses. */
+    witnesses: ShellTxWitness[];
+}
 /** Paginated response from `shell_getTransactionsByAddress`. */
 export interface ShellTxByAddressPage {
     address: AddressLike;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "shell-sdk",
-  "version": "0.2.0",
-  "description": "TypeScript SDK for Shell Chain",
+  "version": "0.3.0",
+  "description": "TypeScript SDK for Shell Chain — build quantum-safe dApps before Q-Day.",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -53,7 +53,7 @@
     "build": "tsc -p tsconfig.json",
     "clean": "rm -rf dist",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "npm run build && node --test tests/**/*.test.mjs"
+    "test": "npm run build && node --test tests/*.test.mjs"
   },
   "keywords": [
     "shell-chain",