shell-sdk 0.1.0

package/dist/transactions.d.ts

@@ -0,0 +1,208 @@
+import type { AddressLike, HexString, ShellSignature, ShellTransactionRequest, SignedShellTransaction, SignatureTypeName } from "./types.js";
+/** Default transaction type: `2` (EIP-1559). */
+export declare const DEFAULT_TX_TYPE = 2;
+/** Default gas limit for simple SHELL token transfers (`21_000`). */
+export declare const DEFAULT_TRANSFER_GAS_LIMIT = 21000;
+/** Default gas limit for system contract calls (`100_000`). */
+export declare const DEFAULT_SYSTEM_GAS_LIMIT = 100000;
+/** Default EIP-1559 max fee per gas: `1_000_000_000` wei (1 Gwei). */
+export declare const DEFAULT_MAX_FEE_PER_GAS = 1000000000;
+/** Default EIP-1559 priority fee (tip) per gas: `100_000_000` wei (0.1 Gwei). */
+export declare const DEFAULT_MAX_PRIORITY_FEE_PER_GAS = 100000000;
+/** Options accepted by {@link buildTransaction}. */
+export interface BuildTransactionOptions {
+    /** EIP-155 chain ID. Devnet = 424242. */
+    chainId: number;
+    /** Sender account nonce. */
+    nonce: number;
+    /** Recipient address, or `null` for contract deployment. */
+    to: AddressLike | null;
+    /** Transfer value in wei. Defaults to `0n`. */
+    value?: bigint;
+    /** ABI-encoded calldata. Defaults to `"0x"`. */
+    data?: HexString;
+    /** Gas limit. Defaults to {@link DEFAULT_TRANSFER_GAS_LIMIT}. */
+    gasLimit?: number;
+    /** EIP-1559 max fee per gas in wei. Defaults to {@link DEFAULT_MAX_FEE_PER_GAS}. */
+    maxFeePerGas?: number;
+    /** EIP-1559 priority fee in wei. Defaults to {@link DEFAULT_MAX_PRIORITY_FEE_PER_GAS}. */
+    maxPriorityFeePerGas?: number;
+    /** Transaction type. Defaults to {@link DEFAULT_TX_TYPE}. */
+    txType?: number;
+    /** Optional EIP-2930 access list. */
+    accessList?: ShellTransactionRequest["access_list"];
+    /** EIP-4844 max fee per blob gas. */
+    maxFeePerBlobGas?: number | null;
+    /** EIP-4844 blob versioned hashes. */
+    blobVersionedHashes?: HexString[] | null;
+}
+/** Options accepted by {@link buildSignedTransaction}. */
+export interface BuildSignedTransactionOptions {
+    /** Sender address (pq1… bech32m form). */
+    from: AddressLike;
+    /** The unsigned transaction payload. */
+    tx: ShellTransactionRequest;
+    /** Raw signature bytes. */
+    signature: Uint8Array | number[];
+    /** Algorithm that produced the signature. */
+    signatureType: SignatureTypeName;
+    /** Optional public key bytes to embed as `sender_pubkey`. */
+    senderPubkey?: Uint8Array | number[];
+}
+/**
+ * Low-level transaction builder that maps camelCase options to the
+ * snake_case wire format expected by the Shell node.
+ *
+ * Prefer the higher-level helpers ({@link buildTransferTransaction},
+ * {@link buildRotateKeyTransaction}, etc.) for common use cases.
+ *
+ * @param options - Transaction fields; all optional fields fall back to safe defaults.
+ * @returns A `ShellTransactionRequest` ready for signing.
+ */
+export declare function buildTransaction(options: BuildTransactionOptions): ShellTransactionRequest;
+/**
+ * Build a SHELL token transfer transaction (type-2 EIP-1559).
+ *
+ * Sets `data` to `"0x"` and applies the transfer gas limit default.
+ *
+ * @param options - Transfer options. `to` is required; `value` defaults to `0n`.
+ * @returns A `ShellTransactionRequest` for a plain token transfer.
+ *
+ * @example
+ * ```typescript
+ * import { parseEther } from "viem";
+ *
+ * const tx = buildTransferTransaction({
+ *   chainId: 424242,
+ *   nonce: 0,
+ *   to: "pq1recipient…",
+ *   value: parseEther("1.5"),
+ * });
+ * ```
+ */
+export declare function buildTransferTransaction(options: Omit<BuildTransactionOptions, "data" | "to"> & {
+    to: AddressLike;
+}): ShellTransactionRequest;
+/**
+ * Build a transaction directed at the AccountManager system contract.
+ *
+ * Sets `to` to {@link accountManagerAddress}, `value` to `0n`, and applies
+ * the system gas limit default. Used internally by the higher-level system
+ * transaction builders.
+ *
+ * @param options - Must include `data` (ABI-encoded calldata); `to` and `value` are fixed.
+ * @returns A `ShellTransactionRequest` targeting the AccountManager.
+ */
+export declare function buildSystemTransaction(options: Omit<BuildTransactionOptions, "to" | "value"> & {
+    data: HexString;
+}): ShellTransactionRequest;
+/**
+ * Build a `rotateKey` transaction that replaces the signing key for the
+ * sender's account.
+ *
+ * After this transaction is confirmed, the account can only be controlled
+ * by the new private key.
+ *
+ * @param options.chainId - EIP-155 chain ID.
+ * @param options.nonce - Sender nonce.
+ * @param options.publicKey - New public key bytes.
+ * @param options.algorithmId - Numeric algorithm ID for the new key (0/1/2).
+ * @param options.gasLimit - Override the default system gas limit.
+ * @returns A `ShellTransactionRequest` that calls `rotateKey(bytes,uint8)` on AccountManager.
+ *
+ * @example
+ * ```typescript
+ * const tx = buildRotateKeyTransaction({
+ *   chainId: 424242,
+ *   nonce: 5,
+ *   publicKey: newAdapter.getPublicKey(),
+ *   algorithmId: 1, // MlDsa65
+ * });
+ * ```
+ */
+export declare function buildRotateKeyTransaction(options: {
+    chainId: number;
+    nonce: number;
+    publicKey: Uint8Array;
+    algorithmId: number;
+    gasLimit?: number;
+}): ShellTransactionRequest;
+/**
+ * Build a `setValidationCode` transaction that attaches a custom EVM
+ * validation contract to the sender's account (smart account / AA).
+ *
+ * @param options.chainId - EIP-155 chain ID.
+ * @param options.nonce - Sender nonce.
+ * @param options.codeHash - `bytes32` hash of the validation contract.
+ * @param options.gasLimit - Override the default system gas limit.
+ * @returns A `ShellTransactionRequest` that calls `setValidationCode(bytes32)`.
+ */
+export declare function buildSetValidationCodeTransaction(options: {
+    chainId: number;
+    nonce: number;
+    codeHash: HexString;
+    gasLimit?: number;
+}): ShellTransactionRequest;
+/**
+ * Build a `clearValidationCode` transaction that removes the custom
+ * validation contract and reverts the account to default PQ key validation.
+ *
+ * @param options.chainId - EIP-155 chain ID.
+ * @param options.nonce - Sender nonce.
+ * @param options.gasLimit - Override the default system gas limit.
+ * @returns A `ShellTransactionRequest` that calls `clearValidationCode()`.
+ */
+export declare function buildClearValidationCodeTransaction(options: {
+    chainId: number;
+    nonce: number;
+    gasLimit?: number;
+}): ShellTransactionRequest;
+/**
+ * Build a {@link ShellSignature} object from raw signature bytes.
+ *
+ * @param signatureType - The algorithm that produced the signature.
+ * @param signature - Raw signature bytes (Uint8Array or number[]).
+ * @returns A `ShellSignature` with `sig_type` and `data`.
+ */
+export declare function buildSignature(signatureType: SignatureTypeName, signature: Uint8Array | number[]): ShellSignature;
+/**
+ * Assemble a {@link SignedShellTransaction} from individual components.
+ *
+ * In practice, use {@link ShellSigner.buildSignedTransaction} which handles
+ * signing and assembly in one step.
+ *
+ * @param options - Sender address, unsigned tx, raw signature bytes, and algorithm name.
+ * @returns A complete `SignedShellTransaction` ready to broadcast.
+ */
+export declare function buildSignedTransaction(options: BuildSignedTransactionOptions): SignedShellTransaction;
+/**
+ * Encode a `Uint8Array` as a `0x`-prefixed hex string.
+ *
+ * @param bytes - Bytes to encode.
+ * @returns A `HexString`.
+ */
+export declare function hexBytes(bytes: Uint8Array): HexString;
+/**
+ * RLP-encode a `ShellTransactionRequest` and return its keccak256 hash.
+ *
+ * This is the signing hash that must be passed to `ShellSigner.buildSignedTransaction`
+ * (or `signer.sign`). Shell Chain computes it identically on the node side as
+ * `keccak256(RLP(tx))` — the same scheme as Ethereum EIP-1559 signing.
+ *
+ * **Encoding order** (EIP-2718 type-2 fields):
+ * chainId, nonce, maxPriorityFeePerGas, maxFeePerGas, gasLimit,
+ * to, value, data, accessList, maxFeePerBlobGas (if present), blobVersionedHashes (if present)
+ *
+ * @example
+ * ```typescript
+ * import { buildTransferTransaction, hashTransaction } from "shell-sdk/transactions";
+ *
+ * const tx     = buildTransferTransaction({ chainId: 424242, nonce: 0, to: "pq1…", value: 1n });
+ * const txHash = hashTransaction(tx);
+ * const signed = await signer.buildSignedTransaction({ tx, txHash });
+ * ```
+ *
+ * @param tx - The unsigned transaction to hash.
+ * @returns 32-byte keccak256 hash as a `Uint8Array`.
+ */
+export declare function hashTransaction(tx: ShellTransactionRequest): Uint8Array;

package/dist/transactions.js

@@ -0,0 +1,250 @@
+/**
+ * Transaction builders for Shell Chain.
+ *
+ * Provides typed helpers for constructing `ShellTransactionRequest` objects
+ * for common operations: token transfers, system contract calls, key rotation,
+ * and custom validation code management.
+ *
+ * @module transactions
+ */
+import { bytesToHex, keccak256, toRlp, numberToHex, hexToBytes } from "viem";
+import { accountManagerAddress, encodeClearValidationCodeCalldata, encodeRotateKeyCalldata, encodeSetValidationCodeCalldata, } from "./system-contracts.js";
+/** Default transaction type: `2` (EIP-1559). */
+export const DEFAULT_TX_TYPE = 2;
+/** Default gas limit for simple SHELL token transfers (`21_000`). */
+export const DEFAULT_TRANSFER_GAS_LIMIT = 21_000;
+/** Default gas limit for system contract calls (`100_000`). */
+export const DEFAULT_SYSTEM_GAS_LIMIT = 100_000;
+/** Default EIP-1559 max fee per gas: `1_000_000_000` wei (1 Gwei). */
+export const DEFAULT_MAX_FEE_PER_GAS = 1_000_000_000;
+/** Default EIP-1559 priority fee (tip) per gas: `100_000_000` wei (0.1 Gwei). */
+export const DEFAULT_MAX_PRIORITY_FEE_PER_GAS = 100_000_000;
+function toByteArray(bytes) {
+    return Array.from(bytes);
+}
+function toHexData(data) {
+    return data ?? "0x";
+}
+/**
+ * Low-level transaction builder that maps camelCase options to the
+ * snake_case wire format expected by the Shell node.
+ *
+ * Prefer the higher-level helpers ({@link buildTransferTransaction},
+ * {@link buildRotateKeyTransaction}, etc.) for common use cases.
+ *
+ * @param options - Transaction fields; all optional fields fall back to safe defaults.
+ * @returns A `ShellTransactionRequest` ready for signing.
+ */
+export function buildTransaction(options) {
+    return {
+        chain_id: options.chainId,
+        nonce: options.nonce,
+        to: options.to,
+        value: `0x${(options.value ?? 0n).toString(16)}`,
+        data: toHexData(options.data),
+        gas_limit: options.gasLimit ?? DEFAULT_TRANSFER_GAS_LIMIT,
+        max_fee_per_gas: options.maxFeePerGas ?? DEFAULT_MAX_FEE_PER_GAS,
+        max_priority_fee_per_gas: options.maxPriorityFeePerGas ?? DEFAULT_MAX_PRIORITY_FEE_PER_GAS,
+        access_list: options.accessList ?? null,
+        tx_type: options.txType ?? DEFAULT_TX_TYPE,
+        max_fee_per_blob_gas: options.maxFeePerBlobGas ?? null,
+        blob_versioned_hashes: options.blobVersionedHashes ?? null,
+    };
+}
+/**
+ * Build a SHELL token transfer transaction (type-2 EIP-1559).
+ *
+ * Sets `data` to `"0x"` and applies the transfer gas limit default.
+ *
+ * @param options - Transfer options. `to` is required; `value` defaults to `0n`.
+ * @returns A `ShellTransactionRequest` for a plain token transfer.
+ *
+ * @example
+ * ```typescript
+ * import { parseEther } from "viem";
+ *
+ * const tx = buildTransferTransaction({
+ *   chainId: 424242,
+ *   nonce: 0,
+ *   to: "pq1recipient…",
+ *   value: parseEther("1.5"),
+ * });
+ * ```
+ */
+export function buildTransferTransaction(options) {
+    return buildTransaction({
+        ...options,
+        data: "0x",
+        gasLimit: options.gasLimit ?? DEFAULT_TRANSFER_GAS_LIMIT,
+    });
+}
+/**
+ * Build a transaction directed at the AccountManager system contract.
+ *
+ * Sets `to` to {@link accountManagerAddress}, `value` to `0n`, and applies
+ * the system gas limit default. Used internally by the higher-level system
+ * transaction builders.
+ *
+ * @param options - Must include `data` (ABI-encoded calldata); `to` and `value` are fixed.
+ * @returns A `ShellTransactionRequest` targeting the AccountManager.
+ */
+export function buildSystemTransaction(options) {
+    return buildTransaction({
+        ...options,
+        to: accountManagerAddress,
+        value: 0n,
+        gasLimit: options.gasLimit ?? DEFAULT_SYSTEM_GAS_LIMIT,
+    });
+}
+/**
+ * Build a `rotateKey` transaction that replaces the signing key for the
+ * sender's account.
+ *
+ * After this transaction is confirmed, the account can only be controlled
+ * by the new private key.
+ *
+ * @param options.chainId - EIP-155 chain ID.
+ * @param options.nonce - Sender nonce.
+ * @param options.publicKey - New public key bytes.
+ * @param options.algorithmId - Numeric algorithm ID for the new key (0/1/2).
+ * @param options.gasLimit - Override the default system gas limit.
+ * @returns A `ShellTransactionRequest` that calls `rotateKey(bytes,uint8)` on AccountManager.
+ *
+ * @example
+ * ```typescript
+ * const tx = buildRotateKeyTransaction({
+ *   chainId: 424242,
+ *   nonce: 5,
+ *   publicKey: newAdapter.getPublicKey(),
+ *   algorithmId: 1, // MlDsa65
+ * });
+ * ```
+ */
+export function buildRotateKeyTransaction(options) {
+    return buildSystemTransaction({
+        chainId: options.chainId,
+        nonce: options.nonce,
+        data: encodeRotateKeyCalldata(options.publicKey, options.algorithmId),
+        gasLimit: options.gasLimit ?? DEFAULT_SYSTEM_GAS_LIMIT,
+    });
+}
+/**
+ * Build a `setValidationCode` transaction that attaches a custom EVM
+ * validation contract to the sender's account (smart account / AA).
+ *
+ * @param options.chainId - EIP-155 chain ID.
+ * @param options.nonce - Sender nonce.
+ * @param options.codeHash - `bytes32` hash of the validation contract.
+ * @param options.gasLimit - Override the default system gas limit.
+ * @returns A `ShellTransactionRequest` that calls `setValidationCode(bytes32)`.
+ */
+export function buildSetValidationCodeTransaction(options) {
+    return buildSystemTransaction({
+        chainId: options.chainId,
+        nonce: options.nonce,
+        data: encodeSetValidationCodeCalldata(options.codeHash),
+        gasLimit: options.gasLimit ?? DEFAULT_SYSTEM_GAS_LIMIT,
+    });
+}
+/**
+ * Build a `clearValidationCode` transaction that removes the custom
+ * validation contract and reverts the account to default PQ key validation.
+ *
+ * @param options.chainId - EIP-155 chain ID.
+ * @param options.nonce - Sender nonce.
+ * @param options.gasLimit - Override the default system gas limit.
+ * @returns A `ShellTransactionRequest` that calls `clearValidationCode()`.
+ */
+export function buildClearValidationCodeTransaction(options) {
+    return buildSystemTransaction({
+        chainId: options.chainId,
+        nonce: options.nonce,
+        data: encodeClearValidationCodeCalldata(),
+        gasLimit: options.gasLimit ?? DEFAULT_SYSTEM_GAS_LIMIT,
+    });
+}
+/**
+ * Build a {@link ShellSignature} object from raw signature bytes.
+ *
+ * @param signatureType - The algorithm that produced the signature.
+ * @param signature - Raw signature bytes (Uint8Array or number[]).
+ * @returns A `ShellSignature` with `sig_type` and `data`.
+ */
+export function buildSignature(signatureType, signature) {
+    return {
+        sig_type: signatureType,
+        data: toByteArray(signature),
+    };
+}
+/**
+ * Assemble a {@link SignedShellTransaction} from individual components.
+ *
+ * In practice, use {@link ShellSigner.buildSignedTransaction} which handles
+ * signing and assembly in one step.
+ *
+ * @param options - Sender address, unsigned tx, raw signature bytes, and algorithm name.
+ * @returns A complete `SignedShellTransaction` ready to broadcast.
+ */
+export function buildSignedTransaction(options) {
+    return {
+        from: options.from,
+        tx: options.tx,
+        signature: buildSignature(options.signatureType, options.signature),
+        sender_pubkey: options.senderPubkey ? toByteArray(options.senderPubkey) : null,
+    };
+}
+/**
+ * Encode a `Uint8Array` as a `0x`-prefixed hex string.
+ *
+ * @param bytes - Bytes to encode.
+ * @returns A `HexString`.
+ */
+export function hexBytes(bytes) {
+    return bytesToHex(bytes);
+}
+/**
+ * RLP-encode a `ShellTransactionRequest` and return its keccak256 hash.
+ *
+ * This is the signing hash that must be passed to `ShellSigner.buildSignedTransaction`
+ * (or `signer.sign`). Shell Chain computes it identically on the node side as
+ * `keccak256(RLP(tx))` — the same scheme as Ethereum EIP-1559 signing.
+ *
+ * **Encoding order** (EIP-2718 type-2 fields):
+ * chainId, nonce, maxPriorityFeePerGas, maxFeePerGas, gasLimit,
+ * to, value, data, accessList, maxFeePerBlobGas (if present), blobVersionedHashes (if present)
+ *
+ * @example
+ * ```typescript
+ * import { buildTransferTransaction, hashTransaction } from "shell-sdk/transactions";
+ *
+ * const tx     = buildTransferTransaction({ chainId: 424242, nonce: 0, to: "pq1…", value: 1n });
+ * const txHash = hashTransaction(tx);
+ * const signed = await signer.buildSignedTransaction({ tx, txHash });
+ * ```
+ *
+ * @param tx - The unsigned transaction to hash.
+ * @returns 32-byte keccak256 hash as a `Uint8Array`.
+ */
+export function hashTransaction(tx) {
+    const to = tx.to ? hexToBytes(tx.to.startsWith("0x") ? tx.to : `0x${tx.to}`) : new Uint8Array(0);
+    const data = hexToBytes(tx.data);
+    const value = hexToBytes(tx.value);
+    const fields = [
+        numberToHex(tx.chain_id),
+        numberToHex(tx.nonce),
+        numberToHex(tx.max_priority_fee_per_gas),
+        numberToHex(tx.max_fee_per_gas),
+        numberToHex(tx.gas_limit),
+        bytesToHex(to),
+        bytesToHex(value),
+        bytesToHex(data),
+        "0x", // empty access list
+    ];
+    if (tx.max_fee_per_blob_gas != null) {
+        fields.push(numberToHex(tx.max_fee_per_blob_gas));
+        fields.push("0x"); // empty blob versioned hashes
+    }
+    const rlpEncoded = toRlp(fields);
+    const hash = hexToBytes(keccak256(rlpEncoded));
+    return hash;
+}

package/dist/types.d.ts

@@ -0,0 +1,140 @@
+/** A `0x`-prefixed hex string, e.g. `"0xdeadbeef"`. */
+export type HexString = `0x${string}`;
+/** Any string accepted as an address — either a `pq1…` bech32m address or a `0x…` hex address. */
+export type AddressLike = string;
+/** A single entry in an EIP-2930 access list. */
+export interface ShellAccessListItem {
+    address: AddressLike;
+    storage_keys: HexString[];
+}
+/**
+ * Wire format for a Shell Chain transaction, sent as part of a {@link SignedShellTransaction}.
+ *
+ * Mirrors the JSON structure expected by the `shell_sendTransaction` RPC method.
+ * Use the builder helpers in `transactions.ts` rather than constructing this object manually.
+ */
+export interface ShellTransactionRequest {
+    /** EIP-155 chain ID. Devnet = 424242. */
+    chain_id: number;
+    /** Sender account nonce. */
+    nonce: number;
+    /** Recipient address (pq1… or 0x…), or `null` for contract deployment. */
+    to: AddressLike | null;
+    /** Transfer value as a hex-encoded bigint string, e.g. `"0xde0b6b3a7640000"`. */
+    value: string;
+    /** ABI-encoded call data, or `"0x"` for plain transfers. */
+    data: HexString;
+    /** Maximum gas units the transaction may consume. */
+    gas_limit: number;
+    /** EIP-1559 maximum fee per gas unit (in wei). */
+    max_fee_per_gas: number;
+    /** EIP-1559 priority fee (tip) per gas unit (in wei). */
+    max_priority_fee_per_gas: number;
+    /** Optional EIP-2930 access list. */
+    access_list?: ShellAccessListItem[] | null;
+    /** Transaction type; defaults to `2` (EIP-1559). */
+    tx_type?: number;
+    /** EIP-4844 max fee per blob gas unit. */
+    max_fee_per_blob_gas?: number | null;
+    /** EIP-4844 blob versioned hashes. */
+    blob_versioned_hashes?: HexString[] | null;
+}
+/**
+ * The name of a supported post-quantum signature algorithm.
+ *
+ * - `"Dilithium3"` — Round-3 Dilithium (algorithm ID 0); uses the ML-DSA-65 implementation as a stand-in.
+ * - `"MlDsa65"` — NIST FIPS 204 ML-DSA-65 (algorithm ID 1).
+ * - `"SphincsSha2256f"` — NIST FIPS 205 SLH-DSA-SHA2-256f (algorithm ID 2).
+ */
+export type SignatureTypeName = "Dilithium3" | "MlDsa65" | "SphincsSha2256f";
+/**
+ * A post-quantum signature attached to a transaction.
+ *
+ * `data` contains the raw signature bytes serialised as a plain number array
+ * to ensure JSON compatibility without base64 encoding overhead.
+ */
+export interface ShellSignature {
+    /** Algorithm that produced this signature. */
+    sig_type: SignatureTypeName;
+    /** Raw signature bytes as a JS number array. */
+    data: number[];
+}
+/**
+ * A fully-signed Shell Chain transaction ready to broadcast via `shell_sendTransaction`.
+ *
+ * @example
+ * ```typescript
+ * const signed: SignedShellTransaction = await signer.buildSignedTransaction({ tx, txHash });
+ * const hash = await provider.sendTransaction(signed);
+ * ```
+ */
+export interface SignedShellTransaction {
+    /** Sender address (pq1… bech32m form). */
+    from: AddressLike;
+    /** The unsigned transaction payload. */
+    tx: ShellTransactionRequest;
+    /** PQ signature produced by the sender's private key. */
+    signature: ShellSignature;
+    /**
+     * Raw public key bytes of the sender.
+     * Required when the account has not yet appeared on-chain so the node can
+     * verify the address derivation. Pass `null` for subsequent transactions.
+     */
+    sender_pubkey?: number[] | null;
+}
+/** Paginated response from `shell_getTransactionsByAddress`. */
+export interface ShellTxByAddressPage {
+    address: AddressLike;
+    page: number;
+    limit: number;
+    total: number;
+    transactions: unknown[];
+}
+/** Parameters for `shell_sendTransaction`. */
+export interface ShellSendTransactionParams {
+    signedTransaction: SignedShellTransaction;
+}
+/** argon2id KDF parameters stored in a Shell keystore file. */
+export interface ShellKdfParams {
+    /** Memory cost in KiB (argon2id `m`). */
+    m_cost: number;
+    /** Time cost / iteration count (argon2id `t`). */
+    t_cost: number;
+    /** Parallelism factor (argon2id `p`). */
+    p_cost: number;
+    /** Hex-encoded random salt. */
+    salt: string;
+}
+/** xchacha20-poly1305 cipher parameters stored in a Shell keystore file. */
+export interface ShellCipherParams {
+    /** Hex-encoded 24-byte nonce. */
+    nonce: string;
+}
+/**
+ * The JSON structure of an encrypted Shell keystore file.
+ *
+ * Generated by the Shell CLI (`shell key generate`). Decrypt with
+ * {@link decryptKeystore} from `keystore.ts`.
+ *
+ * Plaintext layout after decryption: `[secret_key_bytes][public_key_bytes]`.
+ */
+export interface ShellEncryptedKey {
+    /** Schema version (currently `1`). */
+    version: number;
+    /** bech32m `pq1…` address corresponding to the encrypted key. */
+    address: string;
+    /** Key algorithm identifier string, e.g. `"mldsa65"` or `"sphincs-sha2-256f"`. */
+    key_type: string;
+    /** KDF algorithm name; currently always `"argon2id"`. */
+    kdf: string;
+    /** argon2id parameters. */
+    kdf_params: ShellKdfParams;
+    /** Cipher algorithm name; currently always `"xchacha20-poly1305"`. */
+    cipher: string;
+    /** Cipher nonce. */
+    cipher_params: ShellCipherParams;
+    /** Hex-encoded authenticated ciphertext (includes poly1305 tag). */
+    ciphertext: string;
+    /** Hex-encoded raw public key bytes. */
+    public_key: string;
+}

package/dist/types.js

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

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "shell-sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for Shell Chain",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./address": {
+      "types": "./dist/address.d.ts",
+      "import": "./dist/address.js"
+    },
+    "./provider": {
+      "types": "./dist/provider.d.ts",
+      "import": "./dist/provider.js"
+    },
+    "./signer": {
+      "types": "./dist/signer.d.ts",
+      "import": "./dist/signer.js"
+    },
+    "./adapters": {
+      "types": "./dist/adapters.d.ts",
+      "import": "./dist/adapters.js"
+    },
+    "./keystore": {
+      "types": "./dist/keystore.d.ts",
+      "import": "./dist/keystore.js"
+    },
+    "./transactions": {
+      "types": "./dist/transactions.d.ts",
+      "import": "./dist/transactions.js"
+    },
+    "./system-contracts": {
+      "types": "./dist/system-contracts.d.ts",
+      "import": "./dist/system-contracts.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "keywords": [
+    "shell-chain",
+    "sdk",
+    "viem",
+    "typescript",
+    "pq"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShellDAO/shell-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ShellDAO/shell-sdk/issues"
+  },
+  "homepage": "https://github.com/ShellDAO/shell-sdk#readme",
+  "dependencies": {
+    "@noble/ciphers": "^2.1.1",
+    "@noble/hashes": "^1.8.0",
+    "@noble/post-quantum": "^0.6.0",
+    "@scure/base": "^1.2.6",
+    "hash-wasm": "^4.12.0",
+    "viem": "^2.39.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0"
+  }
+}