@qrlwallet/connect 5.0.3 → 5.1.1

package/README.md

@@ -9,8 +9,9 @@ Account validation and message-signature verification use the complete 64-byte
 address. Applications using legacy 20-byte addresses must remain on version 4
 until their network and wallet support QIP-55.
 
-Wallet typed-data requests are disabled pending a versioned 64-byte address
-encoding. The local verifier remains available for address-free typed data.
+`qrl_signTypedData` signs payloads with QIP-55 address fields under
+`QRL-SIGN-TYPED-v2` (one 64-byte word per value); address-free payloads keep
+`QRL-SIGN-TYPED-v1`. See docs/JSON-RPC-REFERENCE.md.
 The private v3 network is a test network; its availability does not establish
 compatibility with legacy deployments or contracts.
 
@@ -173,16 +174,16 @@ The main class. Creates a connection manager and EIP-1193 provider.
 **Require user approval:**
 `qrl_requestAccounts`, `qrl_sendTransaction`, `qrl_signTransaction`, `qrl_signMessage`, `qrl_signTypedData`, `wallet_switchQrlChain`
 
-`qrl_signMessage` uses SHAKE256 plus native ML-DSA-87 ctx and returns a rich `{ signature, publicKey, descriptor, signer, digest, schemeVersion }` object. During the QIP-55 port, `qrl_signTypedData` stays in the approval policy and fails locally before relay use. Its v1 encoding fixes addresses to a 32-byte slot, so a new 64-byte encoding needs a new scheme version and regenerated wallet parity vectors.
+`qrl_signMessage` and `qrl_signTypedData` use SHAKE256 plus native ML-DSA-87 ctx and return a rich `{ signature, publicKey, descriptor, signer, digest, schemeVersion }` object (typed data also echoes `domain`). Typed data with QIP-55 address fields is signed under `QRL-SIGN-TYPED-v2`, address-free typed data under `QRL-SIGN-TYPED-v1`.
 
 `request()` returns `unknown`. First validate the exact response shape with
 `isQrlSignedMessageResult` or `isQrlSignedTypedDataResult`, then require
 `hasSigningDescriptor`. PQP3 authenticates the paired transport session. It
 does not prove that the returned ML-DSA signature is valid or that its public
 key belongs to the claimed signer. Authentication and authorization flows must
-call `verifyMessageForSigner` or the historical v1 `verifyTypedDataForSigner`
-with the original challenge or payload and the expected QIP-55 Q + 128 hex
-address.
+call `verifyMessageForSigner` or `verifyTypedDataForSigner` (pass the
+response's `schemeVersion`) with the original challenge or payload and the
+expected QIP-55 Q + 128 hex address.
 
 The lower-level `verifyMessageSignature` / `verifyTypedDataSignature` helpers
 verify only the supplied key and signature; they do not prove that the key

package/dist/index.d.mts

@@ -269,8 +269,8 @@ interface EIP6963ProviderInfoOverride {
     rdns?: string;
 }
 /**
- * Rich response object returned by `qrl_signMessage` and retained for locked
- * `qrl_signTypedData` v1 fixtures. The signature alone is not enough to
+ * Rich response object returned by `qrl_signMessage` and
+ * `qrl_signTypedData`. The signature alone is not enough to
  * verify since ML-DSA-87 public keys cannot be recovered from a signature,
  * so the wallet returns the public key explicitly. Stateless verifiers need
  * the original payload plus the signature fields below.
@@ -290,24 +290,26 @@ interface QrlSignedResult {
     signer: string;
     /** 0x-hex of the 64-byte SHAKE256 digest that was signed. */
     digest: string;
-    /** Scheme tag: 'QRL-SIGN-MSG-v1' or 'QRL-SIGN-TYPED-v1'. */
+    /** Scheme tag: 'QRL-SIGN-MSG-v1', 'QRL-SIGN-TYPED-v1' or 'QRL-SIGN-TYPED-v2'. */
     schemeVersion: QrlSigningSchemeVersion;
 }
 /** A current wallet response whose descriptor can be signer-bound. */
 interface QrlSignedResultWithDescriptor extends QrlSignedResult {
     descriptor: string;
 }
-type QrlSigningSchemeVersion = 'QRL-SIGN-MSG-v1' | 'QRL-SIGN-TYPED-v1';
+type QrlSigningSchemeVersion = 'QRL-SIGN-MSG-v1' | 'QRL-SIGN-TYPED-v1' | 'QRL-SIGN-TYPED-v2';
 /** Strict wire shape returned by `qrl_signMessage`. */
 interface QrlSignedMessageResult extends QrlSignedResult {
     schemeVersion: 'QRL-SIGN-MSG-v1';
 }
 /**
- * Historical v1 response from `qrl_signTypedData`. It echoes `domain` so a
- * stateless verifier does not need to be told the domain out-of-band.
+ * Response from `qrl_signTypedData`. It echoes `domain` so a stateless
+ * verifier does not need to be told the domain out-of-band. The scheme is
+ * v2 when the payload's types reach an `address` field and v1 otherwise;
+ * pass `schemeVersion` to `verifyTypedDataForSigner` to have it checked.
  */
 interface QrlSignedTypedDataResult extends QrlSignedResult {
-    schemeVersion: 'QRL-SIGN-TYPED-v1';
+    schemeVersion: 'QRL-SIGN-TYPED-v1' | 'QRL-SIGN-TYPED-v2';
     domain: Record<string, unknown>;
 }
 /** Every strict signing-result wire shape understood by this SDK. */
@@ -338,10 +340,9 @@ declare function hasSigningDescriptor(result: unknown): result is QrlSigningResu
  */
 type QrlSignMessageParams = [string, string];
 /**
- * Reserved `qrl_signTypedData` params: `[signer, payload]`. This interface
- * describes the historical v1 payload retained by the verifier exports. The
- * QIP-55 provider rejects requests until a versioned 64-byte encoding is
- * defined.
+ * `qrl_signTypedData` params: `[signer, payload]`. A payload whose types
+ * reach an `address` field is signed under QRL-SIGN-TYPED-v2, any other
+ * under v1.
  */
 interface QrlTypedDataPayload {
     types: Record<string, readonly {
@@ -870,8 +871,17 @@ declare class SocketClient extends EventEmitter<SocketClientEvents> {
  */
 declare const SCHEME_VERSION_MSG = "QRL-SIGN-MSG-v1";
 declare const SCHEME_VERSION_TYPED = "QRL-SIGN-TYPED-v1";
+/**
+ * Typed data with 64-byte slots, one QRVM word per atomic value, so a QIP-55
+ * address fits. A payload uses it exactly when an `address` type is
+ * reachable from QRLDomain or the primary type; every other payload keeps
+ * v1. See typedData.ts.
+ */
+declare const SCHEME_VERSION_TYPED_V2 = "QRL-SIGN-TYPED-v2";
+type TypedDataSchemeVersion = typeof SCHEME_VERSION_TYPED | typeof SCHEME_VERSION_TYPED_V2;
 declare const SCHEME_TAG_MSG: Uint8Array;
 declare const SCHEME_TAG_TYPED: Uint8Array;
+declare const SCHEME_TAG_TYPED_V2: Uint8Array;
 /** SHAKE256 output length used throughout the signing module (NIST L5-matched). */
 declare const DIGEST_LEN = 64;
 
@@ -887,7 +897,7 @@ declare const DIGEST_LEN = 64;
 declare function computeMessageDigest(messageBytes: Uint8Array): Uint8Array;
 
 /**
- * Historical EIP-712-shaped typed-data encoding for `qrl_signTypedData` v1.
+ * EIP-712-shaped typed-data encoding for `qrl_signTypedData`.
  *
  * Byte-identical algorithm with the wallet's signing/typedData.ts; this
  * file is the SDK port (only the import block differs: the SDK routes
@@ -895,10 +905,19 @@ declare function computeMessageDigest(messageBytes: Uint8Array): Uint8Array;
  * the wallet copy for the spec-level comments; behavior must stay in
  * lock-step or the cross-repo parity test fails on next CI.
  *
- * The v1 address slot is 32 bytes. QIP-55 address fields fail closed until a
- * 64-byte encoding receives a new scheme tag and lockstep wallet fixtures.
- * Address-free digests retain their existing encoding.
+ * Two schemes share this codec and differ only in the atomic slot size:
+ * - QRL-SIGN-TYPED-v1: 32-byte slots, the original layout.
+ * - QRL-SIGN-TYPED-v2: 64-byte slots, one QRVM word per atomic value, so a
+ *   64-byte QIP-55 address fits one slot. Integers are zero- or
+ *   sign-extended over 512 bits, bool and address are left-padded, bytesN
+ *   is right-padded.
+ * Strings, bytes, arrays, structs and type hashes are 64-byte SHAKE256
+ * digests in both. A payload uses v2 exactly when an `address` type
+ * (including address arrays) is reachable from QRLDomain or the primary
+ * type, so address-free payloads keep their v1 digests and older verifiers
+ * keep working for them.
  */
+
 declare const TYPED_DATA_LIMITS: Readonly<{
     maxTypes: 32;
     maxFieldsPerType: 32;
@@ -928,8 +947,25 @@ interface TypedDataPayload {
 }
 declare function encodeType(primary: string, types: TypeMap): string;
 declare function typeHash(primary: string, types: TypeMap): Uint8Array;
-declare function encodeField(type: FieldType, value: unknown, types: TypeMap): Uint8Array;
-declare function hashStruct(primary: string, data: Message, types: TypeMap): Uint8Array;
+/**
+ * Encode one field. The scheme defaults to the one `types` selects (v2 when
+ * any struct has an address field), which matches computeTypedDataDigest
+ * when `types` is a payload's full type map.
+ */
+declare function encodeField(type: FieldType, value: unknown, types: TypeMap, schemeVersion?: TypedDataSchemeVersion): Uint8Array;
+/**
+ * Hash one struct. The scheme defaults to the one `types` selects (v2 when
+ * any struct has an address field), which matches computeTypedDataDigest
+ * when `types` is a payload's full type map.
+ */
+declare function hashStruct(primary: string, data: Message, types: TypeMap, schemeVersion?: TypedDataSchemeVersion): Uint8Array;
+/**
+ * The scheme a payload is signed and verified under. It follows from the
+ * payload's types alone, so wallet and verifier agree without negotiating.
+ */
+declare function typedDataSchemeVersion(payload: unknown): TypedDataSchemeVersion;
+/** The digest-preimage and ML-DSA-87 ctx tag of a typed-data scheme. */
+declare function typedDataSchemeTag(schemeVersion: TypedDataSchemeVersion): Uint8Array;
 declare function computeTypedDataDigest(payload: unknown): Uint8Array;
 
 /**
@@ -961,13 +997,18 @@ interface VerifyTypedDataParams {
     signature: Uint8Array | string;
     publicKey: Uint8Array | string;
     payload: TypedDataPayload;
+    /**
+     * The `schemeVersion` from the wallet response. Optional: the payload's
+     * types decide the scheme, and a supplied value must match it.
+     */
+    schemeVersion?: string | undefined;
 }
 /**
  * Verify against an explicitly supplied ML-DSA public key only. This does not
  * bind that key to a Q-address. Use verifyTypedDataForSigner when signer
  * identity matters.
  */
-declare function verifyTypedDataSignature({ signature, publicKey, payload, }: VerifyTypedDataParams): boolean;
+declare function verifyTypedDataSignature({ signature, publicKey, payload, schemeVersion, }: VerifyTypedDataParams): boolean;
 interface VerifyMessageForSignerParams extends VerifyMessageParams {
     /** QIP-55 Q + 128 hex address expected by the dApp. */
     expectedSigner: string;
@@ -983,7 +1024,7 @@ interface VerifyTypedDataForSignerParams extends VerifyTypedDataParams {
     descriptor?: Uint8Array | string | undefined;
 }
 /** Verify both the typed-data signature and public-key-to-signer binding. */
-declare function verifyTypedDataForSigner({ expectedSigner, descriptor, signature, publicKey, payload, }: VerifyTypedDataForSignerParams): boolean;
+declare function verifyTypedDataForSigner({ expectedSigner, descriptor, signature, publicKey, payload, schemeVersion, }: VerifyTypedDataForSignerParams): boolean;
 /**
  * @deprecated Use verifyMessageSignature for a key-only check, or
  * verifyMessageForSigner when signer identity matters.
@@ -1135,4 +1176,4 @@ declare function isValidJsonRpcMethod(value: unknown): value is string;
  */
 declare function classifyRpcMethod(method: string): RpcMethodPolicy;
 
-export { type AckMessage, BLOB_LEN, CAP_LEN, CID_LEN, ConnectionManager, ConnectionStatus, type DAppMetadata, type DAppSession, DEFAULT_RELAY_URL, DIGEST_LEN, type Domain, type EIP6963ProviderInfoOverride, EXPLICITLY_UNSUPPORTED_METHODS, FP_LEN, type InitiatedKeyExchange, type JsonRpcRequest, type JsonRpcResponse, KeyExchange, KeyExchangeMessageType, MAX_CONNECTION_URI_LENGTH, MAX_JSON_RPC_ID_LENGTH, MAX_JSON_RPC_METHOD_LENGTH, MAX_RELAY_URL_LENGTH, ML_DSA_87_PUBLIC_KEY_BYTES, ML_DSA_87_SIGNATURE_BYTES, ML_DSA_DESCRIPTOR_BYTES, type Message, MessageType, PAIRING_CAPABILITY_LEN, PROTOCOL_VERSION, type ParsedURI, type PendingRequest, type PersistedSession, type ProviderEvents, QRLConnectProvider as QRLConnect, type QRLConnectOptions, QRLConnectProvider, QRL_ADDRESS_BYTES, QRL_ADDRESS_HEX_LENGTH, QRL_CONNECT_PROVIDER_INFO, type QrlSignMessageParams, type QrlSignTypedDataParams, type QrlSignedMessageResult, type QrlSignedResult, type QrlSignedResultWithDescriptor, type QrlSignedTypedDataResult, type QrlSigningResult, type QrlSigningSchemeVersion, type QrlTypedDataPayload, RESTRICTED_METHODS, type RelayMessage, type RpcMethodPolicy, SCHEME_TAG_MSG, SCHEME_TAG_TYPED, SCHEME_VERSION_MSG, SCHEME_VERSION_TYPED, type Session, SocketClient, type StructDef, type SynAckMessage, TYPED_DATA_LIMITS, type TypeMap, type TypedDataPayload, type TypedField, UNRESTRICTED_METHODS, type VerifyMessageForSignerParams, type VerifyMessageParams, type VerifyTypedDataForSignerParams, type VerifyTypedDataParams, attemptWalletRedirect, bytesToHex, cidFromString, cidRandom, cidToString, classifyRpcMethod, computeFingerprint, computeMessageDigest, computeTypedDataDigest, concatBytes, encodeField, encodeType, fingerprintEquals, formatQrlAddressFingerprint, generateConnectionURI, getAppStoreUrl, hasSigningDescriptor, hashStruct, hexToBytes, isCurrentQrlAddress, isMobileBrowser, isQrlSignedMessageResult, isQrlSignedResult, isQrlSignedTypedDataResult, isValidJsonRpcId, isValidJsonRpcMethod, normalizeRelayUrl, parseConnectionURI, qip55AddressFromBytes, typeHash, verifyMessage, verifyMessageForSigner, verifyMessageSignature, verifyTypedData, verifyTypedDataForSigner, verifyTypedDataSignature };
+export { type AckMessage, BLOB_LEN, CAP_LEN, CID_LEN, ConnectionManager, ConnectionStatus, type DAppMetadata, type DAppSession, DEFAULT_RELAY_URL, DIGEST_LEN, type Domain, type EIP6963ProviderInfoOverride, EXPLICITLY_UNSUPPORTED_METHODS, FP_LEN, type InitiatedKeyExchange, type JsonRpcRequest, type JsonRpcResponse, KeyExchange, KeyExchangeMessageType, MAX_CONNECTION_URI_LENGTH, MAX_JSON_RPC_ID_LENGTH, MAX_JSON_RPC_METHOD_LENGTH, MAX_RELAY_URL_LENGTH, ML_DSA_87_PUBLIC_KEY_BYTES, ML_DSA_87_SIGNATURE_BYTES, ML_DSA_DESCRIPTOR_BYTES, type Message, MessageType, PAIRING_CAPABILITY_LEN, PROTOCOL_VERSION, type ParsedURI, type PendingRequest, type PersistedSession, type ProviderEvents, QRLConnectProvider as QRLConnect, type QRLConnectOptions, QRLConnectProvider, QRL_ADDRESS_BYTES, QRL_ADDRESS_HEX_LENGTH, QRL_CONNECT_PROVIDER_INFO, type QrlSignMessageParams, type QrlSignTypedDataParams, type QrlSignedMessageResult, type QrlSignedResult, type QrlSignedResultWithDescriptor, type QrlSignedTypedDataResult, type QrlSigningResult, type QrlSigningSchemeVersion, type QrlTypedDataPayload, RESTRICTED_METHODS, type RelayMessage, type RpcMethodPolicy, SCHEME_TAG_MSG, SCHEME_TAG_TYPED, SCHEME_TAG_TYPED_V2, SCHEME_VERSION_MSG, SCHEME_VERSION_TYPED, SCHEME_VERSION_TYPED_V2, type Session, SocketClient, type StructDef, type SynAckMessage, TYPED_DATA_LIMITS, type TypeMap, type TypedDataPayload, type TypedDataSchemeVersion, type TypedField, UNRESTRICTED_METHODS, type VerifyMessageForSignerParams, type VerifyMessageParams, type VerifyTypedDataForSignerParams, type VerifyTypedDataParams, attemptWalletRedirect, bytesToHex, cidFromString, cidRandom, cidToString, classifyRpcMethod, computeFingerprint, computeMessageDigest, computeTypedDataDigest, concatBytes, encodeField, encodeType, fingerprintEquals, formatQrlAddressFingerprint, generateConnectionURI, getAppStoreUrl, hasSigningDescriptor, hashStruct, hexToBytes, isCurrentQrlAddress, isMobileBrowser, isQrlSignedMessageResult, isQrlSignedResult, isQrlSignedTypedDataResult, isValidJsonRpcId, isValidJsonRpcMethod, normalizeRelayUrl, parseConnectionURI, qip55AddressFromBytes, typeHash, typedDataSchemeTag, typedDataSchemeVersion, verifyMessage, verifyMessageForSigner, verifyMessageSignature, verifyTypedData, verifyTypedDataForSigner, verifyTypedDataSignature };

package/dist/index.d.ts

@@ -269,8 +269,8 @@ interface EIP6963ProviderInfoOverride {
     rdns?: string;
 }
 /**
- * Rich response object returned by `qrl_signMessage` and retained for locked
- * `qrl_signTypedData` v1 fixtures. The signature alone is not enough to
+ * Rich response object returned by `qrl_signMessage` and
+ * `qrl_signTypedData`. The signature alone is not enough to
  * verify since ML-DSA-87 public keys cannot be recovered from a signature,
  * so the wallet returns the public key explicitly. Stateless verifiers need
  * the original payload plus the signature fields below.
@@ -290,24 +290,26 @@ interface QrlSignedResult {
     signer: string;
     /** 0x-hex of the 64-byte SHAKE256 digest that was signed. */
     digest: string;
-    /** Scheme tag: 'QRL-SIGN-MSG-v1' or 'QRL-SIGN-TYPED-v1'. */
+    /** Scheme tag: 'QRL-SIGN-MSG-v1', 'QRL-SIGN-TYPED-v1' or 'QRL-SIGN-TYPED-v2'. */
     schemeVersion: QrlSigningSchemeVersion;
 }
 /** A current wallet response whose descriptor can be signer-bound. */
 interface QrlSignedResultWithDescriptor extends QrlSignedResult {
     descriptor: string;
 }
-type QrlSigningSchemeVersion = 'QRL-SIGN-MSG-v1' | 'QRL-SIGN-TYPED-v1';
+type QrlSigningSchemeVersion = 'QRL-SIGN-MSG-v1' | 'QRL-SIGN-TYPED-v1' | 'QRL-SIGN-TYPED-v2';
 /** Strict wire shape returned by `qrl_signMessage`. */
 interface QrlSignedMessageResult extends QrlSignedResult {
     schemeVersion: 'QRL-SIGN-MSG-v1';
 }
 /**
- * Historical v1 response from `qrl_signTypedData`. It echoes `domain` so a
- * stateless verifier does not need to be told the domain out-of-band.
+ * Response from `qrl_signTypedData`. It echoes `domain` so a stateless
+ * verifier does not need to be told the domain out-of-band. The scheme is
+ * v2 when the payload's types reach an `address` field and v1 otherwise;
+ * pass `schemeVersion` to `verifyTypedDataForSigner` to have it checked.
  */
 interface QrlSignedTypedDataResult extends QrlSignedResult {
-    schemeVersion: 'QRL-SIGN-TYPED-v1';
+    schemeVersion: 'QRL-SIGN-TYPED-v1' | 'QRL-SIGN-TYPED-v2';
     domain: Record<string, unknown>;
 }
 /** Every strict signing-result wire shape understood by this SDK. */
@@ -338,10 +340,9 @@ declare function hasSigningDescriptor(result: unknown): result is QrlSigningResu
  */
 type QrlSignMessageParams = [string, string];
 /**
- * Reserved `qrl_signTypedData` params: `[signer, payload]`. This interface
- * describes the historical v1 payload retained by the verifier exports. The
- * QIP-55 provider rejects requests until a versioned 64-byte encoding is
- * defined.
+ * `qrl_signTypedData` params: `[signer, payload]`. A payload whose types
+ * reach an `address` field is signed under QRL-SIGN-TYPED-v2, any other
+ * under v1.
  */
 interface QrlTypedDataPayload {
     types: Record<string, readonly {
@@ -870,8 +871,17 @@ declare class SocketClient extends EventEmitter<SocketClientEvents> {
  */
 declare const SCHEME_VERSION_MSG = "QRL-SIGN-MSG-v1";
 declare const SCHEME_VERSION_TYPED = "QRL-SIGN-TYPED-v1";
+/**
+ * Typed data with 64-byte slots, one QRVM word per atomic value, so a QIP-55
+ * address fits. A payload uses it exactly when an `address` type is
+ * reachable from QRLDomain or the primary type; every other payload keeps
+ * v1. See typedData.ts.
+ */
+declare const SCHEME_VERSION_TYPED_V2 = "QRL-SIGN-TYPED-v2";
+type TypedDataSchemeVersion = typeof SCHEME_VERSION_TYPED | typeof SCHEME_VERSION_TYPED_V2;
 declare const SCHEME_TAG_MSG: Uint8Array;
 declare const SCHEME_TAG_TYPED: Uint8Array;
+declare const SCHEME_TAG_TYPED_V2: Uint8Array;
 /** SHAKE256 output length used throughout the signing module (NIST L5-matched). */
 declare const DIGEST_LEN = 64;
 
@@ -887,7 +897,7 @@ declare const DIGEST_LEN = 64;
 declare function computeMessageDigest(messageBytes: Uint8Array): Uint8Array;
 
 /**
- * Historical EIP-712-shaped typed-data encoding for `qrl_signTypedData` v1.
+ * EIP-712-shaped typed-data encoding for `qrl_signTypedData`.
  *
  * Byte-identical algorithm with the wallet's signing/typedData.ts; this
  * file is the SDK port (only the import block differs: the SDK routes
@@ -895,10 +905,19 @@ declare function computeMessageDigest(messageBytes: Uint8Array): Uint8Array;
  * the wallet copy for the spec-level comments; behavior must stay in
  * lock-step or the cross-repo parity test fails on next CI.
  *
- * The v1 address slot is 32 bytes. QIP-55 address fields fail closed until a
- * 64-byte encoding receives a new scheme tag and lockstep wallet fixtures.
- * Address-free digests retain their existing encoding.
+ * Two schemes share this codec and differ only in the atomic slot size:
+ * - QRL-SIGN-TYPED-v1: 32-byte slots, the original layout.
+ * - QRL-SIGN-TYPED-v2: 64-byte slots, one QRVM word per atomic value, so a
+ *   64-byte QIP-55 address fits one slot. Integers are zero- or
+ *   sign-extended over 512 bits, bool and address are left-padded, bytesN
+ *   is right-padded.
+ * Strings, bytes, arrays, structs and type hashes are 64-byte SHAKE256
+ * digests in both. A payload uses v2 exactly when an `address` type
+ * (including address arrays) is reachable from QRLDomain or the primary
+ * type, so address-free payloads keep their v1 digests and older verifiers
+ * keep working for them.
  */
+
 declare const TYPED_DATA_LIMITS: Readonly<{
     maxTypes: 32;
     maxFieldsPerType: 32;
@@ -928,8 +947,25 @@ interface TypedDataPayload {
 }
 declare function encodeType(primary: string, types: TypeMap): string;
 declare function typeHash(primary: string, types: TypeMap): Uint8Array;
-declare function encodeField(type: FieldType, value: unknown, types: TypeMap): Uint8Array;
-declare function hashStruct(primary: string, data: Message, types: TypeMap): Uint8Array;
+/**
+ * Encode one field. The scheme defaults to the one `types` selects (v2 when
+ * any struct has an address field), which matches computeTypedDataDigest
+ * when `types` is a payload's full type map.
+ */
+declare function encodeField(type: FieldType, value: unknown, types: TypeMap, schemeVersion?: TypedDataSchemeVersion): Uint8Array;
+/**
+ * Hash one struct. The scheme defaults to the one `types` selects (v2 when
+ * any struct has an address field), which matches computeTypedDataDigest
+ * when `types` is a payload's full type map.
+ */
+declare function hashStruct(primary: string, data: Message, types: TypeMap, schemeVersion?: TypedDataSchemeVersion): Uint8Array;
+/**
+ * The scheme a payload is signed and verified under. It follows from the
+ * payload's types alone, so wallet and verifier agree without negotiating.
+ */
+declare function typedDataSchemeVersion(payload: unknown): TypedDataSchemeVersion;
+/** The digest-preimage and ML-DSA-87 ctx tag of a typed-data scheme. */
+declare function typedDataSchemeTag(schemeVersion: TypedDataSchemeVersion): Uint8Array;
 declare function computeTypedDataDigest(payload: unknown): Uint8Array;
 
 /**
@@ -961,13 +997,18 @@ interface VerifyTypedDataParams {
     signature: Uint8Array | string;
     publicKey: Uint8Array | string;
     payload: TypedDataPayload;
+    /**
+     * The `schemeVersion` from the wallet response. Optional: the payload's
+     * types decide the scheme, and a supplied value must match it.
+     */
+    schemeVersion?: string | undefined;
 }
 /**
  * Verify against an explicitly supplied ML-DSA public key only. This does not
  * bind that key to a Q-address. Use verifyTypedDataForSigner when signer
  * identity matters.
  */
-declare function verifyTypedDataSignature({ signature, publicKey, payload, }: VerifyTypedDataParams): boolean;
+declare function verifyTypedDataSignature({ signature, publicKey, payload, schemeVersion, }: VerifyTypedDataParams): boolean;
 interface VerifyMessageForSignerParams extends VerifyMessageParams {
     /** QIP-55 Q + 128 hex address expected by the dApp. */
     expectedSigner: string;
@@ -983,7 +1024,7 @@ interface VerifyTypedDataForSignerParams extends VerifyTypedDataParams {
     descriptor?: Uint8Array | string | undefined;
 }
 /** Verify both the typed-data signature and public-key-to-signer binding. */
-declare function verifyTypedDataForSigner({ expectedSigner, descriptor, signature, publicKey, payload, }: VerifyTypedDataForSignerParams): boolean;
+declare function verifyTypedDataForSigner({ expectedSigner, descriptor, signature, publicKey, payload, schemeVersion, }: VerifyTypedDataForSignerParams): boolean;
 /**
  * @deprecated Use verifyMessageSignature for a key-only check, or
  * verifyMessageForSigner when signer identity matters.
@@ -1135,4 +1176,4 @@ declare function isValidJsonRpcMethod(value: unknown): value is string;
  */
 declare function classifyRpcMethod(method: string): RpcMethodPolicy;
 
-export { type AckMessage, BLOB_LEN, CAP_LEN, CID_LEN, ConnectionManager, ConnectionStatus, type DAppMetadata, type DAppSession, DEFAULT_RELAY_URL, DIGEST_LEN, type Domain, type EIP6963ProviderInfoOverride, EXPLICITLY_UNSUPPORTED_METHODS, FP_LEN, type InitiatedKeyExchange, type JsonRpcRequest, type JsonRpcResponse, KeyExchange, KeyExchangeMessageType, MAX_CONNECTION_URI_LENGTH, MAX_JSON_RPC_ID_LENGTH, MAX_JSON_RPC_METHOD_LENGTH, MAX_RELAY_URL_LENGTH, ML_DSA_87_PUBLIC_KEY_BYTES, ML_DSA_87_SIGNATURE_BYTES, ML_DSA_DESCRIPTOR_BYTES, type Message, MessageType, PAIRING_CAPABILITY_LEN, PROTOCOL_VERSION, type ParsedURI, type PendingRequest, type PersistedSession, type ProviderEvents, QRLConnectProvider as QRLConnect, type QRLConnectOptions, QRLConnectProvider, QRL_ADDRESS_BYTES, QRL_ADDRESS_HEX_LENGTH, QRL_CONNECT_PROVIDER_INFO, type QrlSignMessageParams, type QrlSignTypedDataParams, type QrlSignedMessageResult, type QrlSignedResult, type QrlSignedResultWithDescriptor, type QrlSignedTypedDataResult, type QrlSigningResult, type QrlSigningSchemeVersion, type QrlTypedDataPayload, RESTRICTED_METHODS, type RelayMessage, type RpcMethodPolicy, SCHEME_TAG_MSG, SCHEME_TAG_TYPED, SCHEME_VERSION_MSG, SCHEME_VERSION_TYPED, type Session, SocketClient, type StructDef, type SynAckMessage, TYPED_DATA_LIMITS, type TypeMap, type TypedDataPayload, type TypedField, UNRESTRICTED_METHODS, type VerifyMessageForSignerParams, type VerifyMessageParams, type VerifyTypedDataForSignerParams, type VerifyTypedDataParams, attemptWalletRedirect, bytesToHex, cidFromString, cidRandom, cidToString, classifyRpcMethod, computeFingerprint, computeMessageDigest, computeTypedDataDigest, concatBytes, encodeField, encodeType, fingerprintEquals, formatQrlAddressFingerprint, generateConnectionURI, getAppStoreUrl, hasSigningDescriptor, hashStruct, hexToBytes, isCurrentQrlAddress, isMobileBrowser, isQrlSignedMessageResult, isQrlSignedResult, isQrlSignedTypedDataResult, isValidJsonRpcId, isValidJsonRpcMethod, normalizeRelayUrl, parseConnectionURI, qip55AddressFromBytes, typeHash, verifyMessage, verifyMessageForSigner, verifyMessageSignature, verifyTypedData, verifyTypedDataForSigner, verifyTypedDataSignature };
+export { type AckMessage, BLOB_LEN, CAP_LEN, CID_LEN, ConnectionManager, ConnectionStatus, type DAppMetadata, type DAppSession, DEFAULT_RELAY_URL, DIGEST_LEN, type Domain, type EIP6963ProviderInfoOverride, EXPLICITLY_UNSUPPORTED_METHODS, FP_LEN, type InitiatedKeyExchange, type JsonRpcRequest, type JsonRpcResponse, KeyExchange, KeyExchangeMessageType, MAX_CONNECTION_URI_LENGTH, MAX_JSON_RPC_ID_LENGTH, MAX_JSON_RPC_METHOD_LENGTH, MAX_RELAY_URL_LENGTH, ML_DSA_87_PUBLIC_KEY_BYTES, ML_DSA_87_SIGNATURE_BYTES, ML_DSA_DESCRIPTOR_BYTES, type Message, MessageType, PAIRING_CAPABILITY_LEN, PROTOCOL_VERSION, type ParsedURI, type PendingRequest, type PersistedSession, type ProviderEvents, QRLConnectProvider as QRLConnect, type QRLConnectOptions, QRLConnectProvider, QRL_ADDRESS_BYTES, QRL_ADDRESS_HEX_LENGTH, QRL_CONNECT_PROVIDER_INFO, type QrlSignMessageParams, type QrlSignTypedDataParams, type QrlSignedMessageResult, type QrlSignedResult, type QrlSignedResultWithDescriptor, type QrlSignedTypedDataResult, type QrlSigningResult, type QrlSigningSchemeVersion, type QrlTypedDataPayload, RESTRICTED_METHODS, type RelayMessage, type RpcMethodPolicy, SCHEME_TAG_MSG, SCHEME_TAG_TYPED, SCHEME_TAG_TYPED_V2, SCHEME_VERSION_MSG, SCHEME_VERSION_TYPED, SCHEME_VERSION_TYPED_V2, type Session, SocketClient, type StructDef, type SynAckMessage, TYPED_DATA_LIMITS, type TypeMap, type TypedDataPayload, type TypedDataSchemeVersion, type TypedField, UNRESTRICTED_METHODS, type VerifyMessageForSignerParams, type VerifyMessageParams, type VerifyTypedDataForSignerParams, type VerifyTypedDataParams, attemptWalletRedirect, bytesToHex, cidFromString, cidRandom, cidToString, classifyRpcMethod, computeFingerprint, computeMessageDigest, computeTypedDataDigest, concatBytes, encodeField, encodeType, fingerprintEquals, formatQrlAddressFingerprint, generateConnectionURI, getAppStoreUrl, hasSigningDescriptor, hashStruct, hexToBytes, isCurrentQrlAddress, isMobileBrowser, isQrlSignedMessageResult, isQrlSignedResult, isQrlSignedTypedDataResult, isValidJsonRpcId, isValidJsonRpcMethod, normalizeRelayUrl, parseConnectionURI, qip55AddressFromBytes, typeHash, typedDataSchemeTag, typedDataSchemeVersion, verifyMessage, verifyMessageForSigner, verifyMessageSignature, verifyTypedData, verifyTypedDataForSigner, verifyTypedDataSignature };