@rialo/ts-cdk 0.4.2 → 0.8.0-alpha.0

package/dist/index.d.ts

@@ -730,129 +730,71 @@ declare class RialoError extends Error {
     static serialization(message: string): RialoError;
 }
 
-/**
- * Error codes for HPKE encryption operations.
- */
-declare enum HpkeErrorCode {
-    /** Key length does not match expected size */
-    INVALID_KEY_LENGTH = "INVALID_KEY_LENGTH",
-    /** Ciphertext is shorter than minimum required length */
-    CIPHERTEXT_TOO_SHORT = "CIPHERTEXT_TOO_SHORT",
-    /** HPKE encryption operation failed */
+declare enum EncryptionErrorCode {
+    /** Input validation failed (empty secret, oversized secret, invalid key length) */
+    INVALID_INPUT = "INVALID_INPUT",
+    /** Threshold public key is not a valid compressed Ristretto255 point */
+    INVALID_THRESHOLD_KEY = "INVALID_THRESHOLD_KEY",
+    /** DKG encryption operation failed */
     ENCRYPTION_FAILED = "ENCRYPTION_FAILED",
     /** Failed to deserialize Borsh data */
     BORSH_DESERIALIZE_FAILED = "BORSH_DESERIALIZE_FAILED",
     /** RexValue has invalid variant byte */
     INVALID_REX_VALUE = "INVALID_REX_VALUE"
 }
-/**
- * Error class for HPKE encryption operations.
- *
- * Provides detailed error information for encryption failures,
- * including error codes and contextual details.
- */
-declare class HpkeError extends Error {
-    readonly code: HpkeErrorCode;
+declare class EncryptionError extends Error {
+    readonly code: EncryptionErrorCode;
     readonly cause?: Error;
-    constructor(code: HpkeErrorCode, message: string, cause?: Error);
-    /**
-     * Create an error for invalid key length.
-     *
-     * @param expected - Expected key length in bytes
-     * @param actual - Actual key length in bytes
-     * @param keyType - Description of the key type (e.g., "REX public key")
-     */
-    static invalidKeyLength(expected: number, actual: number, keyType: string): HpkeError;
-    /**
-     * Create an error for ciphertext that is too short.
-     *
-     * @param minLength - Minimum required length
-     * @param actual - Actual length
-     */
-    static ciphertextTooShort(minLength: number, actual: number): HpkeError;
-    /**
-     * Create an error for encryption failure.
-     *
-     * @param cause - The underlying error
-     */
-    static encryptionFailed(cause: Error): HpkeError;
-    /**
-     * Create an error for Borsh deserialization failure.
-     *
-     * @param cause - The underlying error
-     */
-    static borshDeserializeFailed(cause: Error): HpkeError;
-    /**
-     * Create an error for invalid RexValue variant.
-     *
-     * @param variant - The invalid variant byte
-     */
-    static invalidRexValue(variant: number): HpkeError;
+    constructor(code: EncryptionErrorCode, message: string, cause?: Error);
+    static invalidInput(message: string): EncryptionError;
+    static invalidThresholdKey(cause: Error): EncryptionError;
+    static encryptionFailed(cause: Error): EncryptionError;
+    static borshDeserializeFailed(cause: Error): EncryptionError;
+    static invalidRexValue(variant: number): EncryptionError;
 }
 
 /**
- * Constants for REX HPKE encryption.
+ * Constants for DKG threshold encryption.
  *
  * These constants MUST match the Rust implementation exactly:
- * - `crates/tee/secret-sharing/src/constants.rs`
+ * - `crates/tee/secret-sharing/src/types.rs`
+ * - `developer-frameworks/cdk/rialo-rs-cdk/src/secret_encryption.rs`
  *
  * @module
  */
 /**
- * Additional Authenticated Data (AAD) prefix for user secrets.
- *
- * This 13-byte string is prepended to the sender's public key to form
- * the complete AAD for HPKE encryption. It provides domain separation
- * to prevent cross-protocol attacks.
+ * Version byte prepended to every DKG threshold-encrypted payload stored in
+ * `RexValue::Encrypted`. Format: `[DKG_PAYLOAD_VERSION] || borsh(DkgEncryptedPayload)`.
  *
- * Format: `USER_SECRET_AAD || senderPubkey` = 45 bytes total AAD
- *
- * @remarks
- * Must match Rust: `pub const USER_SECRET_AAD: &[u8] = b"rex-secret-v1";`
+ * Must match Rust: `pub const DKG_PAYLOAD_VERSION: u8 = 0x02`
  */
-declare const USER_SECRET_AAD: Uint8Array<ArrayBuffer>;
+declare const DKG_PAYLOAD_VERSION = 2;
 /**
- * HPKE info string for secret sharing context.
- *
- * This 32-byte string is used as the `info` parameter in HPKE encryption,
- * providing domain separation for secret sharing operations.
+ * Maximum plaintext length accepted by `encryptSecretBytes` (64 KB).
  *
- * @remarks
- * Must match Rust: `pub const SECRET_SHARING_HPKE_INFO: &[u8; 32] = b"rialo/tee/secret-sharing-hpke/v1";`
+ * Must match Rust: `pub const MAX_SECRET_LENGTH: usize = 64 * 1024`
  */
-declare const SECRET_SHARING_HPKE_INFO: Uint8Array<ArrayBuffer>;
+declare const MAX_SECRET_LENGTH: number;
 /**
- * Length of an X25519 public key in bytes.
+ * Length of a compressed Ristretto255 point in bytes.
  *
- * Used for the REX encryption public key (secret sharing key).
+ * Used for the DKG threshold public key and the ElGamal header point U.
  */
-declare const X25519_PUBLIC_KEY_LENGTH = 32;
+declare const RISTRETTO_POINT_BYTES = 32;
 /**
  * Length of an Ed25519 public key in bytes.
  *
- * Used for sender identity binding in AAD construction.
+ * Used for the creator public key bound into the AAD.
  */
 declare const ED25519_PUBLIC_KEY_LENGTH = 32;
 /**
- * Length of the HPKE encapsulated key (enc) in bytes.
- *
- * For X25519, this is always 32 bytes.
+ * Length of the ChaCha20-Poly1305 nonce in bytes.
  */
-declare const HPKE_ENC_LENGTH = 32;
+declare const CHACHA20_POLY1305_NONCE_LENGTH = 12;
 /**
  * Length of the ChaCha20-Poly1305 authentication tag in bytes.
  */
 declare const CHACHA20_POLY1305_TAG_LENGTH = 16;
-/**
- * Total overhead added by HPKE encryption.
- *
- * This is the additional bytes beyond the plaintext:
- * - enc (32 bytes): Encapsulated ephemeral public key
- * - tag (16 bytes): ChaCha20-Poly1305 authentication tag
- *
- * Ciphertext length = plaintext length + 48 bytes
- */
-declare const HPKE_OVERHEAD_LENGTH: number;
 
 /**
  * Variant discriminator for RexValue Borsh serialization.
@@ -886,7 +828,7 @@ declare enum RexValueVariant {
  * // Plain value (unencrypted)
  * const plain = RexValue.plain(new TextEncoder().encode("hello"));
  *
- * // Encrypted value (via HPKE)
+ * // Encrypted value (via DKG threshold encryption)
  * const encrypted = RexValue.encrypted(ciphertextBytes);
  *
  * // Serialize to Borsh
@@ -915,9 +857,9 @@ declare class RexValue {
      */
     static plainString(s: string): RexValue;
     /**
-     * Create an encrypted RexValue from HPKE ciphertext.
+     * Create an encrypted RexValue from a DKG threshold-encrypted payload.
      *
-     * @param ciphertext - The HPKE-encrypted ciphertext (enc || ct || tag)
+     * @param ciphertext - The DKG-encrypted payload bytes (`[0x02] || borsh(DkgEncryptedPayload)`)
      * @returns A new RexValue with Encrypted variant
      */
     static encrypted(ciphertext: Uint8Array): RexValue;
@@ -959,112 +901,11 @@ declare class RexValue {
      *
      * @param data - The Borsh-serialized bytes
      * @returns A new RexValue
-     * @throws {HpkeError} If deserialization fails
+     * @throws {EncryptionError} If deserialization fails
      */
     static fromBorsh(data: Uint8Array): RexValue;
 }
 
-/**
- * Encrypt data using HPKE for REX secret sharing.
- *
- * This function performs HPKE encryption using the Base mode with:
- * - X25519 for key encapsulation
- * - HKDF-SHA256 for key derivation
- * - ChaCha20-Poly1305 for authenticated encryption
- *
- * The output format is: `enc (32 bytes) || ciphertext || tag (16 bytes)`
- *
- * @param rexPubkey - The REX X25519 public key (32 bytes)
- * @param data - The plaintext data to encrypt
- * @param senderPubkey - The sender's Ed25519 public key (32 bytes) for AAD construction
- * @returns The encrypted ciphertext including enc and tag
- * @throws {HpkeError} If key lengths are invalid or encryption fails
- *
- * @example
- * ```typescript
- * const rexPubkey = await client.getSecretSharingPubkey();
- * const ciphertext = await hpkeEncrypt(
- *   rexPubkey,
- *   new TextEncoder().encode("secret data"),
- *   keypair.publicKey.toBytes()
- * );
- * ```
- */
-declare function hpkeEncrypt(rexPubkey: Uint8Array, data: Uint8Array, senderPubkey: Uint8Array): Promise<Uint8Array>;
-/**
- * Encrypt data for REX and wrap it in an RexValue.
- *
- * This is a convenience function that combines:
- * 1. HPKE encryption using `hpkeEncrypt`
- * 2. Wrapping the ciphertext in an `RexValue.encrypted`
- *
- * The resulting RexValue can be serialized to Borsh and sent to the network.
- *
- * @param rexPubkey - The REX X25519 public key (32 bytes)
- * @param data - The plaintext data to encrypt
- * @param senderPubkey - The sender's Ed25519 public key (32 bytes)
- * @returns An RexValue containing the encrypted ciphertext
- * @throws {HpkeError} If key lengths are invalid or encryption fails
- *
- * @example
- * ```typescript
- * import { RpcClient, Keypair } from "@rialo/ts-cdk";
- * import { encryptForRex, RexValue } from "@rialo/ts-cdk/rex";
- *
- * // Get REX public key from the network
- * const client = new RpcClient("https://rpc.rialo.xyz");
- * const rexPubkey = await client.getSecretSharingPubkey();
- *
- * // Create keypair for signing
- * const keypair = Keypair.generate();
- *
- * // Encrypt secret data
- * const rexValue = await encryptForRex(
- *   rexPubkey,
- *   new TextEncoder().encode("my secret API key"),
- *   keypair.publicKey.toBytes()
- * );
- *
- * // The RexValue can now be serialized and used in transactions
- * const borshBytes = rexValue.toBorsh();
- * ```
- */
-declare function encryptForRex(rexPubkey: Uint8Array, data: Uint8Array, senderPubkey: Uint8Array): Promise<RexValue>;
-/**
- * Calculate the expected ciphertext length for a given plaintext length.
- *
- * The ciphertext consists of:
- * - enc (32 bytes): Encapsulated ephemeral public key
- * - ciphertext (plaintext.length bytes): Encrypted data
- * - tag (16 bytes): ChaCha20-Poly1305 authentication tag
- *
- * @param plaintextLength - Length of the plaintext in bytes
- * @returns Expected ciphertext length
- *
- * @example
- * ```typescript
- * const ciphertextLen = getCiphertextLength(100);
- * console.log(ciphertextLen); // 148 (32 + 100 + 16)
- * ```
- */
-declare function getCiphertextLength(plaintextLength: number): number;
-/**
- * Validate that a ciphertext has a valid length.
- *
- * A valid HPKE ciphertext must be at least 48 bytes (32 enc + 16 tag).
- *
- * @param ciphertext - The ciphertext to validate
- * @returns true if the ciphertext length is valid
- *
- * @example
- * ```typescript
- * if (!isValidCiphertextLength(ciphertext)) {
- *   throw new Error("Ciphertext too short");
- * }
- * ```
- */
-declare function isValidCiphertextLength(ciphertext: Uint8Array): boolean;
-
 /** A 32-byte public key, base58-encoded on the wire. */
 
 /** A 64-byte Ed25519 signature, base58-encoded on the wire. */
@@ -1103,6 +944,17 @@ interface CompiledInstruction$1 {
     /** Instruction data (base58-encoded on the wire). */
     data: string;
 }
+/**
+ * An inner instruction produced by a cross-program invocation (CPI).
+ * Contains the index of the top-level instruction that triggered it
+ * and the compiled instruction itself.
+ */
+interface InnerInstruction {
+    /** Index of the top-level instruction that invoked this CPI. */
+    instructionIndex: number;
+    /** The compiled instruction produced by the CPI. */
+    instruction: CompiledInstruction$1;
+}
 /**
  * Header of a transaction message.
  */
@@ -1141,6 +993,12 @@ interface TransactionStatusMetadata {
     err?: string;
     /** Log messages emitted during execution (if available). */
     logMessages?: string[];
+    /** Inner instructions produced by cross-program invocations (CPIs).
+  Critical for decoding token transfers — most Token-2022 Transfer
+  instructions are CPIs, not top-level instructions. */
+    innerInstructions?: InnerInstruction[];
+    /** Compute units consumed by this transaction. */
+    computeUnitsConsumed?: bigint;
 }
 /**
  * Full response for a transaction query.
@@ -1484,11 +1342,13 @@ interface ConnectedNode {
     connectedMs: bigint;
 }
 /**
- * The TEE's X25519 public key for HPKE encryption.
+ * The active secret-sharing public key exposed by the network.
  */
 interface SecretSharingPubkey {
     /** Hex-encoded public key. */
     publicKey: string;
+    /** Active epoch for the threshold public key. */
+    epoch: bigint;
 }
 /**
  * Request to submit an epoch change (admin-only).
@@ -1499,8 +1359,14 @@ interface ValidatorInfoRequest {
     stake: bigint;
     /** Consensus network address (Multiaddr string). */
     consensusAddress: string;
-    /** State sync network address (Multiaddr string). */
-    stateSyncAddress: string;
+    /** Subdag sync network address (Multiaddr string). */
+    subdagSyncAddress: string;
+    /** Long-lived network-service address for snapshot serving /
+  state-sync (Multiaddr string, TCP, e.g.
+  "/ip4/127.0.0.1/tcp/4300/http"). Stable across all epochs
+  and expected to match the value the validator advertised
+  at genesis. */
+    networkServiceAddress: string;
     /** Validator hostname. */
     hostname: string;
     /** Identity public key. */
@@ -1640,8 +1506,8 @@ interface ValidatorAccountInfo {
     stake: bigint;
     /** Network address for consensus communication. */
     address: string;
-    /** Network address for state synchronization. */
-    stateSyncAddress: string;
+    /** Network address for consensus subdag synchronization. */
+    subdagSyncAddress: string;
 }
 /**
  * SPL Token account balance information.
@@ -1707,6 +1573,149 @@ interface RexInfoAndDuties {
     /** List of duties expecting updates or commitment. */
     duties: RexDuty[];
 }
+/**
+ * Keypair metadata — public information about a derived keypair.
+ * Does NOT contain secret material. Safe to pass around freely.
+ */
+interface DerivedKeypairInfo {
+    /** Keypair index within the keyring. */
+    index: number;
+    /** Public key (32 bytes Ed25519). */
+    pubkey: PublicKey;
+    /** Base58-encoded public key string. */
+    pubkeyString: string;
+    /** HD derivation path, if available. */
+    derivationPath?: string;
+}
+/**
+ * Program loader type.
+ */
+type LoaderType = "riscv" | "loaderV4";
+/**
+ * Configuration for chunked program deployment.
+ * retry delays are u64 to match the native Rust DeploymentConfig timers.
+ * chunk-size and confirmation-batch-size are intentionally u32 (not usize)
+ * because chunk sizes and batch counts never exceed 32-bit range in practice,
+ * and u32 is the widest portable integer in WIT without crossing into u64.
+ */
+interface DeploymentConfig$1 {
+    /** Size of each data chunk in bytes. */
+    chunkSize?: number;
+    /** Maximum number of retry attempts per chunk. */
+    maxRetries?: number;
+    /** Initial retry delay in milliseconds. */
+    retryBaseDelayMs?: bigint;
+    /** Maximum retry delay in milliseconds. */
+    retryMaxDelayMs?: bigint;
+    /** Number of confirmations to batch. */
+    confirmationBatchSize?: number;
+}
+/**
+ * Account metadata for a program invocation instruction.
+ */
+interface InvocationAccountMeta {
+    /** Account public key. */
+    pubkey: PublicKey;
+    /** Whether this account is a signer. */
+    isSigner: boolean;
+    /** Whether this account is writable. */
+    isWritable: boolean;
+}
+/**
+ * A fully assembled program instruction.
+ */
+interface ProgramInstruction {
+    /** Program ID to invoke. */
+    programId: PublicKey;
+    /** Accounts required by the instruction. */
+    accounts: InvocationAccountMeta[];
+    /** Instruction data payload. */
+    data: Uint8Array;
+}
+
+/**
+ * Encrypt raw bytes using the DKG threshold public key.
+ *
+ * Low-level variant for callers that supply an explicit epoch and hex-encoded
+ * threshold public key rather than a full `SecretSharingPubkey` struct.
+ *
+ * Uses ElGamal-style ECIES over Ristretto255 with HKDF-SHA256 key derivation
+ * and ChaCha20-Poly1305 AEAD. The output format is:
+ * `[0x02] || borsh(DkgEncryptedPayload)` — matching the Rust CDK exactly.
+ *
+ * @param plaintext - Raw bytes to encrypt (non-empty, max 64 KB)
+ * @param creatorPubkey - Ed25519 public key (32 bytes) bound into the AAD
+ * @param epoch - DKG epoch identifying the joint public key
+ * @param thresholdPubkeyHex - Hex-encoded compressed Ristretto255 joint public key (32 bytes)
+ * @throws {EncryptionError} On invalid inputs or encryption failure
+ */
+declare function encryptSecretBytesWithEpoch(plaintext: Uint8Array, creatorPubkey: Uint8Array, epoch: bigint, thresholdPubkeyHex: string): Uint8Array;
+/**
+ * Encrypt raw bytes using the active DKG threshold public key.
+ *
+ * Accepts a `SecretSharingPubkey` (as returned by `getSecretSharingPubkey()`)
+ * and produces a versioned `DkgEncryptedPayload` that the network can
+ * threshold-decrypt during REX execution.
+ *
+ * @param plaintext - Raw bytes to encrypt (non-empty, max 64 KB)
+ * @param creatorPubkey - Ed25519 public key (32 bytes) bound into the AAD
+ * @param secretSharingPubkey - Active threshold key metadata from RPC
+ * @throws {EncryptionError} On invalid inputs or encryption failure
+ *
+ * @example
+ * ```typescript
+ * const { publicKey, epoch } = await client.getSecretSharingPubkey();
+ * const payload = encryptSecretBytes(
+ *   new TextEncoder().encode("my-api-key"),
+ *   keypair.publicKey.toBytes(),
+ *   { publicKey, epoch },
+ * );
+ * const rexValue = RexValue.encrypted(payload);
+ * ```
+ */
+declare function encryptSecretBytes(plaintext: Uint8Array, creatorPubkey: Uint8Array, secretSharingPubkey: SecretSharingPubkey): Uint8Array;
+/**
+ * Encrypt a UTF-8 string using the active DKG threshold public key.
+ *
+ * Convenience wrapper around `encryptSecretBytes` for string secrets.
+ *
+ * @param secret - The plaintext string to encrypt (non-empty, max 64 KB)
+ * @param creatorPubkey - Ed25519 public key (32 bytes)
+ * @param secretSharingPubkey - Active threshold key metadata from RPC
+ * @throws {EncryptionError} On invalid inputs or encryption failure
+ *
+ * @example
+ * ```typescript
+ * const payload = encryptSecret(
+ *   "Bearer sk-1234567890abcdef",
+ *   keypair.publicKey.toBytes(),
+ *   await client.getSecretSharingPubkey(),
+ * );
+ * ```
+ */
+declare function encryptSecret(secret: string, creatorPubkey: Uint8Array, secretSharingPubkey: SecretSharingPubkey): Uint8Array;
+/**
+ * Encrypt raw bytes for REX and wrap the result in a `RexValue`.
+ *
+ * Combines `encryptSecretBytes` with `RexValue.encrypted`. The resulting
+ * `RexValue` can be serialized to Borsh and included in transactions.
+ *
+ * @param plaintext - Raw bytes to encrypt
+ * @param creatorPubkey - Ed25519 public key (32 bytes)
+ * @param secretSharingPubkey - Active threshold key metadata from RPC
+ * @throws {EncryptionError} On invalid inputs or encryption failure
+ *
+ * @example
+ * ```typescript
+ * const rexValue = encryptForRex(
+ *   new TextEncoder().encode("my secret"),
+ *   keypair.publicKey.toBytes(),
+ *   await client.getSecretSharingPubkey(),
+ * );
+ * const borshBytes = rexValue.toBorsh();
+ * ```
+ */
+declare function encryptForRex(plaintext: Uint8Array, creatorPubkey: Uint8Array, secretSharingPubkey: SecretSharingPubkey): RexValue;
 
 /**
  * Base client with JSON-RPC protocol handling.
@@ -2103,19 +2112,19 @@ declare abstract class RpcClient {
      */
     abstract getConnectedFullNodes(): Promise<ConnectedNode[]>;
     /**
-     * Gets the TEE's secret sharing public key for HPKE encryption.
+     * Gets the active threshold public key used for secret sharing.
      *
-     * This public key is used to encrypt secrets that only the TEE cluster
-     * can decrypt.
+     * This public key is used to create threshold-encrypted payloads that
+     * the crypto-service committee can decrypt.
      *
      * # Returns
      *
-     * The X25519 public key (hex-encoded) used for HPKE encryption.
+     * The active threshold public key (hex-encoded) plus epoch metadata.
      *
      * # Errors
      *
-     * Returns an error if the RPC call fails, the TEE Registry state account
-     * doesn't exist, or the secret sharing public key has not been registered.
+     * Returns an error if the RPC call fails or no active threshold public key
+     * has been finalized yet.
      */
     abstract getSecretSharingPubkey(): Promise<SecretSharingPubkey>;
     /**
@@ -2629,7 +2638,7 @@ declare class RialoClient extends RpcClient {
      */
     getConnectedFullNodes(): Promise<ConnectedNode[]>;
     /**
-     * Gets the TEE's secret sharing public key for HPKE encryption.
+     * Gets the active secret-sharing public key metadata.
      */
     getSecretSharingPubkey(): Promise<SecretSharingPubkey>;
     /**
@@ -2965,29 +2974,18 @@ declare class QueryRpcClient extends BaseRpcClient {
      */
     getTriggeredTransactions(subscriptionAccount: PublicKey, limit?: number): Promise<TriggeredTransaction[]>;
     /**
-     * Retrieve the REX X25519 public key for secret sharing encryption.
+     * Retrieve the active threshold public key metadata.
      *
-     * This key is used for HPKE encryption when sending encrypted data
-     * that should only be decryptable within the REX execution environment.
-     *
-     * @returns The REX X25519 public key as a 32-byte Uint8Array
-     *
-     * @example
-     * ```typescript
-     * import { encryptForREX } from "@rialo/ts-cdk";
-     *
-     * // Get the REX public key
-     * const rexPubkey = await client.getSecretSharingPubkey();
-     *
-     * // Use it for HPKE encryption
-     * const encrypted = await encryptForRex(
-     *   rexPubkey,
-     *   new TextEncoder().encode("secret data"),
-     *   keypair.publicKey.toBytes()
-     * );
-     * ```
+     * Returns the active threshold public key (a compressed Ristretto point) and
+     * its DKG epoch. Pass the result directly to `encryptSecretBytes`,
+     * `encryptSecret`, or `encryptForRex` to produce a threshold-encrypted
+     * `DkgEncryptedPayload` the network can decrypt during REX execution.
+     */
+    getSecretSharingPubkey(): Promise<SecretSharingPubkey>;
+    /**
+     * @deprecated Use `getSecretSharingPubkey()` instead.
      */
-    getSecretSharingPubkey(): Promise<Uint8Array>;
+    getSecretSharingPubkeyInfo(): Promise<SecretSharingPubkey>;
     /**
      * Get the config hash prefix for replay protection.
      *
@@ -4505,6 +4503,212 @@ declare function getMainnetUrl(): string;
  */
 declare function getLocalnetUrl(): string;
 
+/**
+ * A keyring managing one or more derived keypairs.
+ * Secret material stays inside the keyring — callers interact via
+ * indices and public metadata. No freely-passed keypair resources.
+ *
+ * No direct constructor — keyrings are created via KeyringProvider
+ * (create, create-with-mnemonic, recover-from-mnemonic, load).
+ * Active keypair contract: the active keypair is always index 0 at
+ * creation time. Active-keypair switching is a facade operation not
+ * in the generated contract.
+ */
+/**
+ * Resource `keyring` — generated from spec.wit.
+ *
+ * Extend this class to provide a concrete `Keyring` implementation.
+ * Instance methods are abstract; static methods throw by default (override in subclass).
+ */
+declare abstract class Keyring {
+    /**
+     * Sign a message with the active keypair.
+     * Returns 64-byte Ed25519 signature.
+     */
+    abstract sign(message: Uint8Array): Uint8Array;
+    /**
+     * Verify a signature with the active keypair.
+     */
+    abstract verify(message: Uint8Array, sig: Uint8Array): boolean;
+    /**
+     * Active keypair's public key as base58 string.
+     */
+    abstract pubkeyString(): string;
+    /**
+     * Active keypair's public key (32 bytes).
+     */
+    abstract pubkey(): PublicKey;
+    /**
+     * Get public metadata for a keypair by index.
+     */
+    abstract getKeypairInfo(index: number): DerivedKeypairInfo | undefined;
+    /**
+     * List all keypair indices, sorted ascending.
+     */
+    abstract listKeypairs(): number[];
+    /**
+     * Get public metadata for all keypairs, sorted by ascending index.
+     */
+    abstract getKeypairsInfo(): DerivedKeypairInfo[];
+    /**
+     * Sign with a specific keypair by index.
+     */
+    abstract signWithKeypair(message: Uint8Array, index: number): Uint8Array;
+}
+
+/**
+ * Concrete keyring implementation backed by an in-memory map of derived keypairs.
+ *
+ * Keyrings are created via {@link InMemoryKeyringProvider}, not directly.
+ * The active keypair defaults to index 0. Use {@link setActiveKeypair} to change it.
+ * Secret material stays inside the keyring — callers interact via indices and public metadata.
+ */
+declare class RialoKeyring extends Keyring {
+    private readonly keypairs;
+    private readonly derivationPaths;
+    private activeIndex;
+    constructor(keypairs: Map<number, Keypair>, derivationPaths: Map<number, string | undefined>);
+    /**
+     * Sets the active keypair index (facade operation, not in WIT contract).
+     *
+     * @param index - The keypair index to make active
+     * @throws {RialoError} If the index does not exist in this keyring
+     */
+    setActiveKeypair(index: number): void;
+    private activeKeypair;
+    sign(message: Uint8Array): Uint8Array;
+    verify(message: Uint8Array, sig: Uint8Array): boolean;
+    pubkeyString(): string;
+    pubkey(): PublicKey;
+    getKeypairInfo(index: number): DerivedKeypairInfo | undefined;
+    listKeypairs(): number[];
+    getKeypairsInfo(): DerivedKeypairInfo[];
+    signWithKeypair(message: Uint8Array, index: number): Uint8Array;
+    /**
+     * Securely erases all secret key material from this keyring snapshot.
+     *
+     * Calls {@link Keypair.dispose} on every keypair, zeroing private key bytes.
+     * After disposal, signing and secret-key export will throw. Verification
+     * still works (uses only the public key). Does not affect provider-stored
+     * state or other snapshots.
+     */
+    dispose(): void;
+}
+
+/**
+ * Storage and lifecycle management for keyrings. All methods async (I/O).
+ * No WIT constructor — concrete providers are language-specific
+ * (e.g., InMemoryKeyringProvider::new(), new InMemoryKeyringProvider()).
+ */
+/**
+ * Resource `keyring-provider` — generated from spec.wit.
+ *
+ * Extend this class to provide a concrete `KeyringProvider` implementation.
+ * Instance methods are abstract; static methods throw by default (override in subclass).
+ */
+declare abstract class KeyringProvider {
+    /**
+     * Create a new keyring with a random keypair at index 0.
+     */
+    abstract create(name: string, password: string): Promise<Keyring>;
+    /**
+     * Create a keyring with a generated BIP39 mnemonic.
+     * strength-bits: 128 (12 words) or 256 (24 words).
+     * Initializes exactly one keypair at index 0 derived from the mnemonic.
+     * Returns (keyring, mnemonic_phrase). The mnemonic is returned ONCE
+     * for backup — it is NOT stored on the keyring contract.
+     */
+    abstract createWithMnemonic(name: string, strengthBits: number, password: string): Promise<[Keyring, string]>;
+    /**
+     * Recover a keyring from an existing BIP39 mnemonic phrase.
+     * Initializes one keypair at index 0 derived from the mnemonic.
+     */
+    abstract recoverFromMnemonic(name: string, mnemonic: string, password: string): Promise<Keyring>;
+    /**
+     * Load an existing keyring by name. Active keypair defaults to index 0.
+     */
+    abstract load(name: string, password: string): Promise<Keyring>;
+    /**
+     * List all keyring names, sorted alphabetically.
+     */
+    abstract list(): Promise<string[]>;
+    /**
+     * Check if a keyring exists by name.
+     */
+    abstract exists(name: string): Promise<boolean>;
+    /**
+     * Get the active keypair's public key for a keyring (without loading).
+     */
+    abstract getPublicKey(name: string): Promise<PublicKey>;
+    /**
+     * List all keyrings with their active keypair's public info,
+     * sorted alphabetically by keyring name.
+     */
+    abstract listPublicKeys(): Promise<[string, DerivedKeypairInfo][]>;
+    /**
+     * List keypair metadata for a specific keyring, sorted by ascending index.
+     */
+    abstract listKeypairs(keyringName: string): Promise<DerivedKeypairInfo[]>;
+    /**
+     * Derive a new keypair at the specified index.
+     * Errors with DUPLICATE_KEYPAIR_INDEX if the index already exists.
+     */
+    abstract deriveKeypair(keyringName: string, keypairIndex: number, password: string): Promise<DerivedKeypairInfo>;
+    /**
+     * Import an existing 32-byte Ed25519 secret key into a keyring.
+     * Assigns the next available index (max(existing) + 1).
+     */
+    abstract importSecretKey(keyringName: string, secretKey: Uint8Array, derivationPath: string | undefined, password: string): Promise<DerivedKeypairInfo>;
+    /**
+     * Get metadata for all keypairs in a keyring, sorted by ascending index.
+     */
+    abstract getKeypairsInfo(name: string): Promise<DerivedKeypairInfo[]>;
+    /**
+     * Get metadata for a specific keypair by index.
+     */
+    abstract getKeypairInfo(name: string, keypairIndex: number): Promise<DerivedKeypairInfo>;
+    /**
+     * Returns max(existing indices) + 1, or 0 if empty.
+     * With sparse indices (e.g., 0 and 5 exist), returns 6, not 2.
+     */
+    abstract nextKeypairIndex(name: string): Promise<number>;
+}
+
+/**
+ * In-memory keyring provider for testing and ephemeral use.
+ *
+ * **Security note:** This provider stores keyrings, passwords, and mnemonic
+ * phrases in plaintext memory. It is designed for development, testing, and
+ * ephemeral use cases — NOT for production secret storage. Key material
+ * persists in the JS heap until garbage collected. For production use,
+ * implement a provider backed by encrypted storage or a hardware security module.
+ *
+ * Keyrings are stored in memory only — not persisted between restarts.
+ * Implements the full keyring-provider contract from the WIT spec.
+ */
+declare class InMemoryKeyringProvider extends KeyringProvider {
+    private readonly keyrings;
+    private getStored;
+    private checkPassword;
+    private buildKeyring;
+    private toInfo;
+    private nextIndex;
+    create(name: string, password: string): Promise<Keyring>;
+    createWithMnemonic(name: string, strengthBits: number, password: string): Promise<[Keyring, string]>;
+    recoverFromMnemonic(name: string, mnemonicPhrase: string, password: string): Promise<Keyring>;
+    load(name: string, password: string): Promise<Keyring>;
+    list(): Promise<string[]>;
+    exists(name: string): Promise<boolean>;
+    getPublicKey(name: string): Promise<PublicKey>;
+    listPublicKeys(): Promise<[string, DerivedKeypairInfo][]>;
+    listKeypairs(keyringName: string): Promise<DerivedKeypairInfo[]>;
+    deriveKeypair(keyringName: string, keypairIndex: number, password: string): Promise<DerivedKeypairInfo>;
+    importSecretKey(keyringName: string, secretKey: Uint8Array, derivationPath: string | undefined, password: string): Promise<DerivedKeypairInfo>;
+    getKeypairsInfo(name: string): Promise<DerivedKeypairInfo[]>;
+    getKeypairInfo(name: string, keypairIndex: number): Promise<DerivedKeypairInfo>;
+    nextKeypairIndex(name: string): Promise<number>;
+}
+
 /** RISC-V loader program ID (PolkaVM bytecode). */
 declare const RISCV_LOADER_PROGRAM_ID = "RiscVLoader11111111111111111111111111111111";
 /** LoaderV4 program ID (eBPF programs). */
@@ -4635,4 +4839,4 @@ declare function deployInstruction(programAddress: PublicKey, authority: PublicK
  */
 declare function retractInstruction(programAddress: PublicKey, authority: PublicKey): Instruction;
 
-export { type AccountFilter, type AccountFilterParam, type AccountInfo, type AccountMeta, AccountMetaTable, type AllAccountsEntry, BASE_DERIVATION_PATH, BUFFER_BALANCE_FACTOR, BaseRpcClient, BincodeReader, type BincodeSchema, BincodeWriter, type BlockInfo, type Bump, CHACHA20_POLY1305_TAG_LENGTH, type ChainDefinition, type ClusterNodeInfo, type CompiledInstruction, type ConfigHashPrefix, type ConfirmTransactionOptions, type ConfirmedTransaction, type ConnectedNode, CryptoError, CryptoErrorCode, DEFAULT_CHUNK_SIZE, DEFAULT_CONFIRMATION_BATCH_SIZE, DEFAULT_MAX_RETRIES, DEFAULT_NUM_ACCOUNTS, DEFAULT_RETRY_BASE_DELAY_MS, DEFAULT_RETRY_MAX_DELAY_MS, type DeploymentConfig, DeploymentError, DeploymentErrorCode, ED25519_PUBLIC_KEY_LENGTH, type EnumVariant, type EpochConsensusConfigRequest, type EpochInfo, type EventData, type FeeResponse, type GetAccountsByOwnerConfig, type GetAllAccountsConfig, type GetBlockConfig, type GetSignaturesForAddressConfig, type GetTransactionsConfig, type GetValidatorAccountsRequest, type GetWorkflowLineageRequest, type GetWorkflowLineageResponse, HPKE_ENC_LENGTH, HPKE_OVERHEAD_LENGTH, HpkeError, HpkeErrorCode, HttpTransport, type HttpTransportConfig, type IdentifierString, type InferSchema, type Instruction, type IsBlockhashValidResponse, KELVIN_PER_RLO, type Kelvin, Keypair, KeypairSigner, LOADER_V4_PROGRAM_ID, Message, type MessageHeader, Mnemonic, type MnemonicStrength, type OptionalAccountInfo, type OwnerAccount, type PDA, PROGRAM_DATA_OFFSET, PUBLIC_KEY_LENGTH, type PaginationInfo, ProgramDeployment, type ProgramDeploymentOptions, PublicKey, QueryRpcClient, RIALO_DEVNET_CHAIN, RIALO_LOCALNET_CHAIN, RIALO_MAINNET_CHAIN, RIALO_TESTNET_CHAIN, RISCV_LOADER_PROGRAM_ID, type RexDuty, type RexInfoAndDuties, RexValue, RexValueVariant, RialoClient, type RialoClientConfig, RialoError, RialoErrorType, type RialoNetwork, RiscVLoaderInstruction, RpcError, RpcErrorCode, type RpcErrorDetails$1 as RpcErrorDetails, SECRET_KEY_LENGTH, SECRET_SHARING_HPKE_INFO, SIGNATURE_LENGTH, SYSTEM_PROGRAM_ID, Schema, type SecretSharingPubkey, type Seed, type SendAndConfirmOptions, type SendTransactionOptions, Signature$1 as Signature, type SignatureInfo, type SignatureStatus, type Signer, type StakeAccountInfo, type StakeState, type StructField, type SubmitEpochChangeRequest, type SubmitEpochChangeResponse, type Subscription, type SubscriptionAccountMeta, type SubscriptionInstruction, type SubscriptionKind, SystemInstruction, type TimestampRange, type TokenBalance, Transaction, TransactionBuilder, type TransactionData, TransactionError, TransactionErrorCode, type TransactionInfo, type TransactionMessage, type TransactionNodeData, type TransactionResponse, TransactionRpcClient, type TransactionStatusMetadata, type TransactionWithMeta, type TriggerInfo, type TriggeredTransaction, type TruncationReason, URL_DEVNET, URL_LOCALNET, URL_MAINNET, URL_TESTNET, USER_SECRET_AAD, type ValidatorAccountInfo, type ValidatorHealth, type ValidatorInfoRequest, type WorkflowLineage, type WorkflowNode, X25519_PUBLIC_KEY_LENGTH, allocateInstruction, assignInstruction, calculateBackoff, concatBytes, createAccount, createBorshInstruction, createRialoClient, deployInstruction, deserialize, deserializeBorsh, deserializeCompactU16, deserializeStrict, encodeBorshData, encryptForRex, fromBase64, getCiphertextLength, getDefaultRialoClientConfig, getDevnetUrl, getLocalnetUrl, getMainnetUrl, getTestnetUrl, hpkeEncrypt, isOnCurve, isValidCiphertextLength, retractInstruction, seedToBytes, serialize, serializeBorsh, serializeCompactU16, setProgramLengthInstruction, sleep, toBase64, transferInstruction, writeCompactU16, writeInstruction };
+export { type AccountFilter, type AccountFilterParam, type AccountInfo, type AccountMeta, AccountMetaTable, type AllAccountsEntry, BASE_DERIVATION_PATH, BUFFER_BALANCE_FACTOR, BaseRpcClient, BincodeReader, type BincodeSchema, BincodeWriter, type BlockInfo, type Bump, CHACHA20_POLY1305_NONCE_LENGTH, CHACHA20_POLY1305_TAG_LENGTH, type ChainDefinition, type ClusterNodeInfo, type CompiledInstruction, type ConfigHashPrefix, type ConfirmTransactionOptions, type ConfirmedTransaction, type ConnectedNode, CryptoError, CryptoErrorCode, DEFAULT_CHUNK_SIZE, DEFAULT_CONFIRMATION_BATCH_SIZE, DEFAULT_MAX_RETRIES, DEFAULT_NUM_ACCOUNTS, DEFAULT_RETRY_BASE_DELAY_MS, DEFAULT_RETRY_MAX_DELAY_MS, DKG_PAYLOAD_VERSION, type DeploymentConfig, DeploymentError, DeploymentErrorCode, type DerivedKeypairInfo, ED25519_PUBLIC_KEY_LENGTH, EncryptionError, EncryptionErrorCode, type EnumVariant, type EpochConsensusConfigRequest, type EpochInfo, type EventData, type FeeResponse, type DeploymentConfig$1 as GeneratedDeploymentConfig, type GetAccountsByOwnerConfig, type GetAllAccountsConfig, type GetBlockConfig, type GetSignaturesForAddressConfig, type GetTransactionsConfig, type GetValidatorAccountsRequest, type GetWorkflowLineageRequest, type GetWorkflowLineageResponse, HttpTransport, type HttpTransportConfig, type IdentifierString, InMemoryKeyringProvider, type InferSchema, type Instruction, type InvocationAccountMeta, type IsBlockhashValidResponse, KELVIN_PER_RLO, type Kelvin, Keypair, KeypairSigner, Keyring, KeyringProvider, LOADER_V4_PROGRAM_ID, type LoaderType, MAX_SECRET_LENGTH, Message, type MessageHeader, Mnemonic, type MnemonicStrength, type OptionalAccountInfo, type OwnerAccount, type PDA, PROGRAM_DATA_OFFSET, PUBLIC_KEY_LENGTH, type PaginationInfo, ProgramDeployment, type ProgramDeploymentOptions, type ProgramInstruction, PublicKey, QueryRpcClient, RIALO_DEVNET_CHAIN, RIALO_LOCALNET_CHAIN, RIALO_MAINNET_CHAIN, RIALO_TESTNET_CHAIN, RISCV_LOADER_PROGRAM_ID, RISTRETTO_POINT_BYTES, type RexDuty, type RexInfoAndDuties, RexValue, RexValueVariant, RialoClient, type RialoClientConfig, RialoError, RialoErrorType, RialoKeyring, type RialoNetwork, RiscVLoaderInstruction, RpcError, RpcErrorCode, type RpcErrorDetails$1 as RpcErrorDetails, SECRET_KEY_LENGTH, SIGNATURE_LENGTH, SYSTEM_PROGRAM_ID, Schema, type SecretSharingPubkey, type Seed, type SendAndConfirmOptions, type SendTransactionOptions, Signature$1 as Signature, type SignatureInfo, type SignatureStatus, type Signer, type StakeAccountInfo, type StakeState, type StructField, type SubmitEpochChangeRequest, type SubmitEpochChangeResponse, type Subscription, type SubscriptionAccountMeta, type SubscriptionInstruction, type SubscriptionKind, SystemInstruction, type TimestampRange, type TokenBalance, Transaction, TransactionBuilder, type TransactionData, TransactionError, TransactionErrorCode, type TransactionInfo, type TransactionMessage, type TransactionNodeData, type TransactionResponse, TransactionRpcClient, type TransactionStatusMetadata, type TransactionWithMeta, type TriggerInfo, type TriggeredTransaction, type TruncationReason, URL_DEVNET, URL_LOCALNET, URL_MAINNET, URL_TESTNET, type ValidatorAccountInfo, type ValidatorHealth, type ValidatorInfoRequest, type WorkflowLineage, type WorkflowNode, allocateInstruction, assignInstruction, calculateBackoff, concatBytes, createAccount, createBorshInstruction, createRialoClient, deployInstruction, deserialize, deserializeBorsh, deserializeCompactU16, deserializeStrict, encodeBorshData, encryptForRex, encryptSecret, encryptSecretBytes, encryptSecretBytesWithEpoch, fromBase64, getDefaultRialoClientConfig, getDevnetUrl, getLocalnetUrl, getMainnetUrl, getTestnetUrl, isOnCurve, retractInstruction, seedToBytes, serialize, serializeBorsh, serializeCompactU16, setProgramLengthInstruction, sleep, toBase64, transferInstruction, writeCompactU16, writeInstruction };