shell-sdk 0.1.0

package/dist/signer.d.ts

@@ -0,0 +1,161 @@
+import { type BuildSignedTransactionOptions } from "./transactions.js";
+import type { SignedShellTransaction, SignatureTypeName } from "./types.js";
+/**
+ * Maps each {@link SignatureTypeName} to its numeric algorithm ID used in
+ * address derivation and on-chain records.
+ *
+ * - `Dilithium3` → `0`
+ * - `MlDsa65` → `1`
+ * - `SphincsSha2256f` → `2`
+ */
+export declare const SIGNATURE_TYPE_IDS: Record<SignatureTypeName, number>;
+/**
+ * Maps the `key_type` strings found in Shell keystore files to their
+ * corresponding {@link SignatureTypeName}.
+ *
+ * Keys are lowercase; matching is done after calling `.toLowerCase()`.
+ */
+export declare const KEY_TYPE_TO_SIGNATURE_TYPE: Record<string, SignatureTypeName>;
+/**
+ * Minimal interface that any post-quantum signing implementation must satisfy
+ * to be used with {@link ShellSigner}.
+ *
+ * @example
+ * ```typescript
+ * class MyAdapter implements SignerAdapter {
+ *   getPublicKey(): Uint8Array { … }
+ *   async sign(message: Uint8Array): Promise<Uint8Array> { … }
+ * }
+ * ```
+ */
+export interface SignerAdapter {
+    /**
+     * Sign a raw message (the transaction hash bytes) and return the signature.
+     *
+     * @param message - The bytes to sign (typically an RLP-encoded tx hash).
+     * @returns The raw signature bytes.
+     */
+    sign(message: Uint8Array): Promise<Uint8Array>;
+    /** Return the raw public key bytes for this signer. */
+    getPublicKey(): Uint8Array;
+}
+/**
+ * High-level Shell Chain signer.
+ *
+ * Wraps a {@link SignerAdapter} and provides address derivation, signing, and
+ * transaction assembly for Shell Chain.
+ *
+ * @example
+ * ```typescript
+ * import { MlDsa65Adapter } from "shell-sdk/adapters";
+ * import { ShellSigner } from "shell-sdk/signer";
+ *
+ * const adapter = MlDsa65Adapter.generate();
+ * const signer  = new ShellSigner("MlDsa65", adapter);
+ *
+ * console.log(signer.getAddress());    // pq1…
+ * console.log(signer.getHexAddress()); // 0x…
+ * ```
+ */
+export declare class ShellSigner {
+    /** The signature algorithm this signer uses. */
+    readonly signatureType: SignatureTypeName;
+    /** The underlying adapter that performs the actual cryptographic operations. */
+    readonly adapter: SignerAdapter;
+    /**
+     * @param signatureType - The PQ algorithm name.
+     * @param adapter - An adapter providing `sign` and `getPublicKey`.
+     */
+    constructor(signatureType: SignatureTypeName, adapter: SignerAdapter);
+    /**
+     * Numeric algorithm ID for this signer's signature type.
+     *
+     * Used in address derivation and in `rotateKey` calldata.
+     */
+    get algorithmId(): number;
+    /** Return the raw public key bytes from the underlying adapter. */
+    getPublicKey(): Uint8Array;
+    /**
+     * Derive and return the `pq1…` bech32m address for this signer.
+     *
+     * The address is computed deterministically from the public key and algorithm ID.
+     */
+    getAddress(): string;
+    /**
+     * Return the `0x…` hex representation of this signer's address.
+     *
+     * Equivalent to `normalizeHexAddress(signer.getAddress())`.
+     */
+    getHexAddress(): `0x${string}`;
+    /**
+     * Sign a raw byte message with the underlying adapter.
+     *
+     * @param message - Bytes to sign (e.g. RLP-encoded transaction hash).
+     * @returns Raw signature bytes.
+     */
+    sign(message: Uint8Array): Promise<Uint8Array>;
+    /**
+     * Sign a transaction hash and assemble a complete {@link SignedShellTransaction}.
+     *
+     * @param options.tx - The unsigned `ShellTransactionRequest` to embed.
+     * @param options.txHash - The bytes to sign (RLP-encoded EIP-1559 signing hash).
+     * @param options.includePublicKey - When `true`, embeds `sender_pubkey` in the
+     *   result. Required for accounts that have not yet appeared on-chain.
+     * @returns A fully-signed transaction ready for {@link ShellProvider.sendTransaction}.
+     *
+     * @example
+     * ```typescript
+     * const signed = await signer.buildSignedTransaction({
+     *   tx,
+     *   txHash: rlpHashBytes,
+     *   includePublicKey: true,
+     * });
+     * const hash = await provider.sendTransaction(signed);
+     * ```
+     */
+    buildSignedTransaction(options: Omit<BuildSignedTransactionOptions, "from" | "signature" | "signatureType"> & {
+        txHash: Uint8Array;
+        includePublicKey?: boolean;
+    }): Promise<SignedShellTransaction>;
+}
+/**
+ * Convert a keystore `key_type` string to a {@link SignatureTypeName}.
+ *
+ * Matching is case-insensitive and ignores leading/trailing whitespace.
+ *
+ * @param keyType - The `key_type` field from a Shell keystore file (e.g. `"mldsa65"`).
+ * @returns The corresponding `SignatureTypeName`.
+ * @throws {Error} If the key type is not recognised.
+ *
+ * @example
+ * ```typescript
+ * signatureTypeFromKeyType("mldsa65");          // "MlDsa65"
+ * signatureTypeFromKeyType("sphincs-sha2-256f"); // "SphincsSha2256f"
+ * ```
+ */
+export declare function signatureTypeFromKeyType(keyType: string): SignatureTypeName;
+/**
+ * Convert a hex-encoded public key string to a `Uint8Array`.
+ *
+ * Accepts both `0x`-prefixed and bare hex strings.
+ *
+ * @param publicKeyHex - Hex-encoded public key (with or without `0x` prefix).
+ * @returns The decoded public key bytes.
+ *
+ * @example
+ * ```typescript
+ * const pk = publicKeyFromHex("0xabcdef…");
+ * const pk = publicKeyFromHex("abcdef…");
+ * ```
+ */
+export declare function publicKeyFromHex(publicKeyHex: string): Uint8Array;
+/**
+ * Build a {@link ShellSignature} object from raw signature bytes.
+ *
+ * A thin wrapper around {@link buildSignature} from `transactions.ts`.
+ *
+ * @param signatureType - The algorithm that produced the signature.
+ * @param signature - Raw signature bytes.
+ * @returns A `ShellSignature` with `sig_type` and `data` fields.
+ */
+export declare function buildShellSignature(signatureType: SignatureTypeName, signature: Uint8Array): import("./types.js").ShellSignature;

package/dist/signer.js

@@ -0,0 +1,188 @@
+/**
+ * ShellSigner and SignerAdapter — the signing layer for Shell Chain transactions.
+ *
+ * `SignerAdapter` is a minimal interface for plugging in any PQ signing
+ * implementation. Concrete adapters live in `adapters.ts`.
+ *
+ * `ShellSigner` wraps an adapter and adds address derivation, transaction
+ * building, and Shell-specific helpers.
+ *
+ * @module signer
+ */
+import { hexToBytes } from "viem";
+import { derivePqAddressFromPublicKey, normalizeHexAddress, normalizePqAddress } from "./address.js";
+import { buildSignature, buildSignedTransaction, } from "./transactions.js";
+/**
+ * Maps each {@link SignatureTypeName} to its numeric algorithm ID used in
+ * address derivation and on-chain records.
+ *
+ * - `Dilithium3` → `0`
+ * - `MlDsa65` → `1`
+ * - `SphincsSha2256f` → `2`
+ */
+export const SIGNATURE_TYPE_IDS = {
+    Dilithium3: 0,
+    MlDsa65: 1,
+    SphincsSha2256f: 2,
+};
+/**
+ * Maps the `key_type` strings found in Shell keystore files to their
+ * corresponding {@link SignatureTypeName}.
+ *
+ * Keys are lowercase; matching is done after calling `.toLowerCase()`.
+ */
+export const KEY_TYPE_TO_SIGNATURE_TYPE = {
+    dilithium3: "Dilithium3",
+    "sphincs-sha2-256f": "SphincsSha2256f",
+    mldsa65: "MlDsa65",
+};
+/**
+ * High-level Shell Chain signer.
+ *
+ * Wraps a {@link SignerAdapter} and provides address derivation, signing, and
+ * transaction assembly for Shell Chain.
+ *
+ * @example
+ * ```typescript
+ * import { MlDsa65Adapter } from "shell-sdk/adapters";
+ * import { ShellSigner } from "shell-sdk/signer";
+ *
+ * const adapter = MlDsa65Adapter.generate();
+ * const signer  = new ShellSigner("MlDsa65", adapter);
+ *
+ * console.log(signer.getAddress());    // pq1…
+ * console.log(signer.getHexAddress()); // 0x…
+ * ```
+ */
+export class ShellSigner {
+    /** The signature algorithm this signer uses. */
+    signatureType;
+    /** The underlying adapter that performs the actual cryptographic operations. */
+    adapter;
+    /**
+     * @param signatureType - The PQ algorithm name.
+     * @param adapter - An adapter providing `sign` and `getPublicKey`.
+     */
+    constructor(signatureType, adapter) {
+        this.signatureType = signatureType;
+        this.adapter = adapter;
+    }
+    /**
+     * Numeric algorithm ID for this signer's signature type.
+     *
+     * Used in address derivation and in `rotateKey` calldata.
+     */
+    get algorithmId() {
+        return SIGNATURE_TYPE_IDS[this.signatureType];
+    }
+    /** Return the raw public key bytes from the underlying adapter. */
+    getPublicKey() {
+        return this.adapter.getPublicKey();
+    }
+    /**
+     * Derive and return the `pq1…` bech32m address for this signer.
+     *
+     * The address is computed deterministically from the public key and algorithm ID.
+     */
+    getAddress() {
+        return derivePqAddressFromPublicKey(this.getPublicKey(), this.algorithmId);
+    }
+    /**
+     * Return the `0x…` hex representation of this signer's address.
+     *
+     * Equivalent to `normalizeHexAddress(signer.getAddress())`.
+     */
+    getHexAddress() {
+        return normalizeHexAddress(this.getAddress());
+    }
+    /**
+     * Sign a raw byte message with the underlying adapter.
+     *
+     * @param message - Bytes to sign (e.g. RLP-encoded transaction hash).
+     * @returns Raw signature bytes.
+     */
+    async sign(message) {
+        return this.adapter.sign(message);
+    }
+    /**
+     * Sign a transaction hash and assemble a complete {@link SignedShellTransaction}.
+     *
+     * @param options.tx - The unsigned `ShellTransactionRequest` to embed.
+     * @param options.txHash - The bytes to sign (RLP-encoded EIP-1559 signing hash).
+     * @param options.includePublicKey - When `true`, embeds `sender_pubkey` in the
+     *   result. Required for accounts that have not yet appeared on-chain.
+     * @returns A fully-signed transaction ready for {@link ShellProvider.sendTransaction}.
+     *
+     * @example
+     * ```typescript
+     * const signed = await signer.buildSignedTransaction({
+     *   tx,
+     *   txHash: rlpHashBytes,
+     *   includePublicKey: true,
+     * });
+     * const hash = await provider.sendTransaction(signed);
+     * ```
+     */
+    async buildSignedTransaction(options) {
+        const signature = await this.sign(options.txHash);
+        return buildSignedTransaction({
+            from: normalizePqAddress(this.getAddress()),
+            tx: options.tx,
+            signature,
+            signatureType: this.signatureType,
+            senderPubkey: options.includePublicKey ? this.getPublicKey() : undefined,
+        });
+    }
+}
+/**
+ * Convert a keystore `key_type` string to a {@link SignatureTypeName}.
+ *
+ * Matching is case-insensitive and ignores leading/trailing whitespace.
+ *
+ * @param keyType - The `key_type` field from a Shell keystore file (e.g. `"mldsa65"`).
+ * @returns The corresponding `SignatureTypeName`.
+ * @throws {Error} If the key type is not recognised.
+ *
+ * @example
+ * ```typescript
+ * signatureTypeFromKeyType("mldsa65");          // "MlDsa65"
+ * signatureTypeFromKeyType("sphincs-sha2-256f"); // "SphincsSha2256f"
+ * ```
+ */
+export function signatureTypeFromKeyType(keyType) {
+    const normalized = keyType.trim().toLowerCase();
+    const value = KEY_TYPE_TO_SIGNATURE_TYPE[normalized];
+    if (!value) {
+        throw new Error(`unsupported key type: ${keyType}`);
+    }
+    return value;
+}
+/**
+ * Convert a hex-encoded public key string to a `Uint8Array`.
+ *
+ * Accepts both `0x`-prefixed and bare hex strings.
+ *
+ * @param publicKeyHex - Hex-encoded public key (with or without `0x` prefix).
+ * @returns The decoded public key bytes.
+ *
+ * @example
+ * ```typescript
+ * const pk = publicKeyFromHex("0xabcdef…");
+ * const pk = publicKeyFromHex("abcdef…");
+ * ```
+ */
+export function publicKeyFromHex(publicKeyHex) {
+    return hexToBytes(`0x${publicKeyHex.replace(/^0x/i, "")}`);
+}
+/**
+ * Build a {@link ShellSignature} object from raw signature bytes.
+ *
+ * A thin wrapper around {@link buildSignature} from `transactions.ts`.
+ *
+ * @param signatureType - The algorithm that produced the signature.
+ * @param signature - Raw signature bytes.
+ * @returns A `ShellSignature` with `sig_type` and `data` fields.
+ */
+export function buildShellSignature(signatureType, signature) {
+    return buildSignature(signatureType, signature);
+}

package/dist/system-contracts.d.ts

@@ -0,0 +1,65 @@
+import type { AddressLike, HexString } from "./types.js";
+/** Hex address of the ValidatorRegistry system contract (`0x…0001`). */
+export declare const validatorRegistryHexAddress = "0x0000000000000000000000000000000000000001";
+/** Hex address of the AccountManager system contract (`0x…0002`). */
+export declare const accountManagerHexAddress = "0x0000000000000000000000000000000000000002";
+/** `pq1…` bech32m address of the ValidatorRegistry system contract. */
+export declare const validatorRegistryAddress: string;
+/** `pq1…` bech32m address of the AccountManager system contract. */
+export declare const accountManagerAddress: string;
+/** 4-byte ABI function selector for `rotateKey(bytes,uint8)`. */
+export declare const rotateKeySelector: `0x${string}`;
+/** 4-byte ABI function selector for `setValidationCode(bytes32)`. */
+export declare const setValidationCodeSelector: `0x${string}`;
+/** 4-byte ABI function selector for `clearValidationCode()`. */
+export declare const clearValidationCodeSelector: `0x${string}`;
+/**
+ * ABI-encode calldata for `rotateKey(bytes publicKey, uint8 algorithmId)`.
+ *
+ * @param publicKey - Raw bytes of the new public key.
+ * @param algorithmId - Numeric algorithm ID (Dilithium3=0, MlDsa65=1, SphincsSha2256f=2).
+ * @returns `HexString` with the 4-byte selector prepended.
+ *
+ * @example
+ * ```typescript
+ * const data = encodeRotateKeyCalldata(newPublicKey, 1 /* MlDsa65 *\/);
+ * ```
+ */
+export declare function encodeRotateKeyCalldata(publicKey: Uint8Array, algorithmId: number): HexString;
+/**
+ * ABI-encode calldata for `setValidationCode(bytes32 codeHash)`.
+ *
+ * @param codeHash - `bytes32` hash of the custom validation contract.
+ * @returns `HexString` with the 4-byte selector prepended.
+ *
+ * @example
+ * ```typescript
+ * const data = encodeSetValidationCodeCalldata("0xabc123…");
+ * ```
+ */
+export declare function encodeSetValidationCodeCalldata(codeHash: HexString): HexString;
+/**
+ * Return the 4-byte selector for `clearValidationCode()`.
+ *
+ * No parameters are encoded since the function takes no arguments.
+ *
+ * @returns The 4-byte function selector as a `HexString`.
+ */
+export declare function encodeClearValidationCodeCalldata(): HexString;
+/**
+ * Return `true` if `address` refers to one of the Shell system contracts.
+ *
+ * Accepts both `pq1…` and `0x…` forms for the AccountManager and
+ * ValidatorRegistry addresses.
+ *
+ * @param address - Address to test (any format accepted by `AddressLike`).
+ * @returns `true` if the address matches AccountManager or ValidatorRegistry.
+ *
+ * @example
+ * ```typescript
+ * isSystemContractAddress("0x0000000000000000000000000000000000000002"); // true
+ * isSystemContractAddress(accountManagerAddress);                        // true
+ * isSystemContractAddress("pq1someuser…");                               // false
+ * ```
+ */
+export declare function isSystemContractAddress(address: AddressLike): boolean;

package/dist/system-contracts.js

@@ -0,0 +1,105 @@
+/**
+ * System contract addresses and calldata encoders for Shell Chain.
+ *
+ * Shell Chain ships two built-in system contracts at well-known addresses:
+ *
+ * - **ValidatorRegistry** (`0x…0001`) — manages the set of active validators.
+ * - **AccountManager** (`0x…0002`) — handles per-account key rotation and
+ *   custom AA validation code.
+ *
+ * Transactions targeting these contracts should be built with the helpers in
+ * `transactions.ts` (e.g. {@link buildRotateKeyTransaction}).
+ *
+ * @module system-contracts
+ */
+import { bytesToHex, encodeAbiParameters, keccak256, toBytes } from "viem";
+import { bytesToPqAddress } from "./address.js";
+const SYSTEM_ADDRESS_LENGTH = 20;
+function systemAddress(lastByte) {
+    const bytes = new Uint8Array(SYSTEM_ADDRESS_LENGTH);
+    bytes[SYSTEM_ADDRESS_LENGTH - 1] = lastByte;
+    return bytes;
+}
+function selector(signature) {
+    return keccak256(toBytes(signature)).slice(0, 10);
+}
+/** Hex address of the ValidatorRegistry system contract (`0x…0001`). */
+export const validatorRegistryHexAddress = "0x0000000000000000000000000000000000000001";
+/** Hex address of the AccountManager system contract (`0x…0002`). */
+export const accountManagerHexAddress = "0x0000000000000000000000000000000000000002";
+/** `pq1…` bech32m address of the ValidatorRegistry system contract. */
+export const validatorRegistryAddress = bytesToPqAddress(systemAddress(1));
+/** `pq1…` bech32m address of the AccountManager system contract. */
+export const accountManagerAddress = bytesToPqAddress(systemAddress(2));
+/** 4-byte ABI function selector for `rotateKey(bytes,uint8)`. */
+export const rotateKeySelector = selector("rotateKey(bytes,uint8)");
+/** 4-byte ABI function selector for `setValidationCode(bytes32)`. */
+export const setValidationCodeSelector = selector("setValidationCode(bytes32)");
+/** 4-byte ABI function selector for `clearValidationCode()`. */
+export const clearValidationCodeSelector = selector("clearValidationCode()");
+/**
+ * ABI-encode calldata for `rotateKey(bytes publicKey, uint8 algorithmId)`.
+ *
+ * @param publicKey - Raw bytes of the new public key.
+ * @param algorithmId - Numeric algorithm ID (Dilithium3=0, MlDsa65=1, SphincsSha2256f=2).
+ * @returns `HexString` with the 4-byte selector prepended.
+ *
+ * @example
+ * ```typescript
+ * const data = encodeRotateKeyCalldata(newPublicKey, 1 /* MlDsa65 *\/);
+ * ```
+ */
+export function encodeRotateKeyCalldata(publicKey, algorithmId) {
+    const encoded = encodeAbiParameters([
+        { type: "bytes" },
+        { type: "uint8" },
+    ], [bytesToHex(publicKey), algorithmId]);
+    return `${rotateKeySelector}${encoded.slice(2)}`;
+}
+/**
+ * ABI-encode calldata for `setValidationCode(bytes32 codeHash)`.
+ *
+ * @param codeHash - `bytes32` hash of the custom validation contract.
+ * @returns `HexString` with the 4-byte selector prepended.
+ *
+ * @example
+ * ```typescript
+ * const data = encodeSetValidationCodeCalldata("0xabc123…");
+ * ```
+ */
+export function encodeSetValidationCodeCalldata(codeHash) {
+    const encoded = encodeAbiParameters([{ type: "bytes32" }], [codeHash]);
+    return `${setValidationCodeSelector}${encoded.slice(2)}`;
+}
+/**
+ * Return the 4-byte selector for `clearValidationCode()`.
+ *
+ * No parameters are encoded since the function takes no arguments.
+ *
+ * @returns The 4-byte function selector as a `HexString`.
+ */
+export function encodeClearValidationCodeCalldata() {
+    return clearValidationCodeSelector;
+}
+/**
+ * Return `true` if `address` refers to one of the Shell system contracts.
+ *
+ * Accepts both `pq1…` and `0x…` forms for the AccountManager and
+ * ValidatorRegistry addresses.
+ *
+ * @param address - Address to test (any format accepted by `AddressLike`).
+ * @returns `true` if the address matches AccountManager or ValidatorRegistry.
+ *
+ * @example
+ * ```typescript
+ * isSystemContractAddress("0x0000000000000000000000000000000000000002"); // true
+ * isSystemContractAddress(accountManagerAddress);                        // true
+ * isSystemContractAddress("pq1someuser…");                               // false
+ * ```
+ */
+export function isSystemContractAddress(address) {
+    return (address === accountManagerAddress ||
+        address === validatorRegistryAddress ||
+        address === accountManagerHexAddress ||
+        address === validatorRegistryHexAddress);
+}