@openzeppelin/miden-multisig-client 0.18.0-rc.3 → 0.18.1

package/src/transaction/options.ts

@@ -8,8 +8,8 @@ export interface SignatureOptions {
   /**
    * The block the transaction summary binds. Omitted, the store's sync height,
    * which is right for the party creating a proposal. A cosigner or executor
-   * rebuilding a proposal pins it to the proposal's anchor block, or the rebuilt
-   * summary can never match the signed one.
+   * rebuilding a proposal pins it to the block the proposal's summary binds, or
+   * the rebuilt summary can never match the signed one.
    */
   boundBlockNum?: number;
   /**

package/src/transaction/summary.ts

@@ -1,7 +1,9 @@
 import type { MidenClient, TransactionRequest, TransactionSummary } from '@miden-sdk/miden-sdk';
-import { ChainAnchor, Word } from '@miden-sdk/miden-sdk';
-import { BoundBlockNotDeclaredError } from '../multisig/authArgErrors.js';
-import { base64ToUint8Array, normalizeHexWord, uint8ArrayToBase64 } from '../utils/encoding.js';
+import { Word } from '@miden-sdk/miden-sdk';
+import {
+  BoundBlockNotDeclaredError,
+  TransactionSummaryLayoutError,
+} from '../multisig/authArgErrors.js';
 import { requestBoundBlockNum } from './authArgs.js';
 
 /**
@@ -13,24 +15,16 @@ const APPROVAL_EXPIRATION_USER_PARAM_INDEX = 0;
 const SALT_USER_PARAM_OFFSET = 2;
 
 /**
- * The summary binds the block the request's auth args name, and the anchor
- * the store's sync height at capture. A sync landing between the build and the
- * capture leaves them one block apart, and every cosigner's anchor check would
- * then fail on a proposal nothing else is wrong with. Caught here, before the
- * proposal is pushed, so the proposer rebuilds instead.
+ * The serialized summary layout {@link summaryBoundBlockNum} reads, from
+ * `TransactionSummary::write_into` at miden-protocol 0.17.0: the version byte
+ * first, then variable-length fields, then a fixed tail of the block number
+ * (u32, little endian), the block commitment (four 8-byte felts), the
+ * expiration delta (u16) and the six user-param felts, with no length prefix.
  */
-export class SummaryAnchorMismatchError extends Error {
-  readonly retryable = true;
-
-  constructor(details: { anchorCommitmentHex: string; summaryBlockCommitmentHex: string }) {
-    super(
-      `the transaction summary binds block commitment ${details.summaryBlockCommitmentHex} but ` +
-        `the captured chain anchor is ${details.anchorCommitmentHex}; a sync landed between ` +
-        'building the request and capturing its anchor, so rebuild the request and retry',
-    );
-    this.name = 'SummaryAnchorMismatchError';
-  }
-}
+const SUPPORTED_SUMMARY_VERSION = 1;
+const BLOCK_NUMBER_BYTES = 4;
+const BLOCK_COMMITMENT_BYTES = 32;
+const SUMMARY_TAIL_BYTES = BLOCK_NUMBER_BYTES + BLOCK_COMMITMENT_BYTES + 2 + 6 * 8;
 
 /**
  * The Miden client synced and its node still has not produced the block a
@@ -67,57 +61,18 @@ export function isStaleChainError(error: unknown): boolean {
   return message.includes('has been pruned');
 }
 
-/**
- * Derives the summary awaiting authorization for a proposal the caller is
- * creating now, and captures a `ChainAnchor` at the current sync height to ship
- * with it.
- *
- * The summary is derived at the chain tip, like every other execution of a
- * multisig proposal (see {@link executeForSummaryAtTip}). The anchor still
- * travels in the proposal: it names the block the request's auth args bind,
- * which is how a rebuild learns that block, and 0.18.0-rc.1 clients re-execute
- * at it. A proposer builds at the sync height the anchor is captured at, and
- * the check below is what makes that hold.
- */
-export async function executeForSummary(
-  client: MidenClient,
-  accountId: string,
-  txRequest: TransactionRequest,
-): Promise<{ summary: TransactionSummary; anchor: ChainAnchor }> {
-  const anchor = await client.transactions.captureAnchor(txRequest);
-  let summary: TransactionSummary;
-  try {
-    summary = await executeForSummaryAtTip(client, accountId, txRequest);
-  } catch (error) {
-    anchor.free();
-    throw error;
-  }
-
-  const anchorCommitment = anchor.commitment();
-  const summaryBlockCommitment = summary.blockCommitment();
-  const anchorCommitmentHex = normalizeHexWord(anchorCommitment.toHex());
-  const summaryBlockCommitmentHex = normalizeHexWord(summaryBlockCommitment.toHex());
-  anchorCommitment.free?.();
-  summaryBlockCommitment.free?.();
-  if (anchorCommitmentHex !== summaryBlockCommitmentHex) {
-    anchor.free();
-    throw new SummaryAnchorMismatchError({ anchorCommitmentHex, summaryBlockCommitmentHex });
-  }
-  return { summary, anchor };
-}
-
 /**
  * Executes a multisig request at the chain tip to obtain the summary awaiting
- * authorization. This is how cosigners and the executor reproduce a proposal's
- * summary, whatever block they have synced to.
+ * authorization. Proposers derive a new proposal's summary with it, and
+ * cosigners and the executor reproduce it, whatever block they have synced to.
  *
  * Since protocol 0.17 a multisig summary binds the block its auth args name
  * (the bound block), not the block the transaction executes against, so it
  * reproduces at any later tip once the bound block is in the transaction's
  * partial blockchain. The request declares it through `withBlockNumbers`, and
- * foreign accounts, the fee faucet among them, load at the tip. Re-executing at
- * the proposal's anchor instead loads them at the bound block, which a node
- * prunes about 50 blocks later (issue #462).
+ * foreign accounts, the fee faucet among them, load at the tip. Executing at
+ * the bound block instead would load them there, which a node prunes about 50
+ * blocks later (issue #462).
  *
  * The client has to have synced to at least the bound block. When it has not,
  * this syncs once before executing.
@@ -203,58 +158,55 @@ export async function syncToBoundBlock(
 }
 
 /**
- * Executes a transaction at the given `ChainAnchor`'s reference block to
- * obtain the summary awaiting authorization.
+ * Reads the block a multisig transaction summary binds, the counterpart of the
+ * Rust `TransactionSummary::block_number`. Since protocol 0.17 that is the block
+ * the request's multisig auth args name, so it is the proposal's bound block.
  *
- * For a summary that binds the reference block, such as a single-signature
- * one. A multisig proposal's summary binds its bound block instead and is
- * reproduced with {@link executeForSummaryAtTip}: re-executing it at an anchor
- * fails once the node prunes the anchor block's account state.
- */
-export async function executeForSummaryAt(
-  client: MidenClient,
-  accountId: string,
-  txRequest: TransactionRequest,
-  anchor: ChainAnchor,
-): Promise<TransactionSummary> {
-  return client.transactions.preview({
-    operation: 'custom',
-    account: accountId,
-    request: txRequest,
-    anchor,
-  });
-}
-
-/**
- * Serializes a `ChainAnchor` to base64 for the proposal wire payload.
+ * The web SDK exposes no accessor for it, so this reads the serialized summary
+ * (layout above) and checks the block commitment next to it against
+ * `blockCommitment()`, so a layout this client does not know is refused rather
+ * than read at the wrong offset.
+ *
+ * @throws TransactionSummaryLayoutError when the summary is not version 1, is
+ *   too short to hold the tail, or its tail does not hold its block commitment.
  */
-export function chainAnchorToBase64(anchor: ChainAnchor): string {
-  return uint8ArrayToBase64(anchor.serialize());
+export function summaryBoundBlockNum(summary: TransactionSummary): number {
+  const bytes = summary.serialize();
+  const blockCommitment = summary.blockCommitment();
+  try {
+    return readBoundBlockNum(bytes, blockCommitment.serialize());
+  } finally {
+    blockCommitment.free();
+  }
 }
 
-/**
- * Deserializes a `ChainAnchor` from its base64 wire form. `ChainAnchor`
- * deserialization validates the header/chain consistency internally, so a
- * decoded anchor only needs its block commitment checked against the signed
- * transaction summary before the block it names is taken as the one the
- * summary binds.
- */
-export function chainAnchorFromBase64(anchorBase64: string): ChainAnchor {
-  return ChainAnchor.deserialize(base64ToUint8Array(anchorBase64));
+function readBoundBlockNum(bytes: Uint8Array, blockCommitment: Uint8Array): number {
+  if (bytes.length < 1 + SUMMARY_TAIL_BYTES) {
+    throw new TransactionSummaryLayoutError(
+      `${bytes.length} bytes is shorter than the version byte and the ${SUMMARY_TAIL_BYTES}-byte tail`,
+    );
+  }
+  if (bytes[0] !== SUPPORTED_SUMMARY_VERSION) {
+    throw new TransactionSummaryLayoutError(
+      `version ${bytes[0]}, but only version ${SUPPORTED_SUMMARY_VERSION} is supported`,
+    );
+  }
+  const blockNumberOffset = bytes.length - SUMMARY_TAIL_BYTES;
+  const commitmentOffset = blockNumberOffset + BLOCK_NUMBER_BYTES;
+  const tailCommitment = bytes.subarray(commitmentOffset, commitmentOffset + BLOCK_COMMITMENT_BYTES);
+  if (!bytesEqual(tailCommitment, blockCommitment)) {
+    throw new TransactionSummaryLayoutError(
+      'the bytes after the block number are not the summary block commitment',
+    );
+  }
+  return new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(
+    blockNumberOffset,
+    true,
+  );
 }
 
-/**
- * The block a proposal's `chainAnchor` names, which is the block its summary
- * binds: a custom producer rebuilds its request at this block. Decodes the
- * anchor for the one number and frees it.
- */
-export function chainAnchorBlockNum(anchorBase64: string): number {
-  const anchor = chainAnchorFromBase64(anchorBase64);
-  try {
-    return anchor.blockNum();
-  } finally {
-    anchor.free();
-  }
+function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  return a.length === b.length && a.every((byte, index) => byte === b[index]);
 }
 
 /**

package/src/transaction.ts

@@ -11,19 +11,14 @@ export {
 } from './transaction/consumeNotes.js';
 export {
   ChainBehindBoundBlockError,
-  chainAnchorBlockNum,
-  chainAnchorFromBase64,
-  chainAnchorToBase64,
-  executeForSummary,
-  executeForSummaryAt,
   executeForSummaryAtTip,
   prepareTipExecution,
   isStaleChainError,
   requireDeclaredBoundBlock,
   syncToBoundBlock,
   summaryApprovalExpirationBlockNum,
+  summaryBoundBlockNum,
   summarySalt,
-  SummaryAnchorMismatchError,
 } from './transaction/summary.js';
 export {
   buildP2idNoteFromMetadata,

package/src/types/proposal.ts

@@ -38,11 +38,17 @@ interface BaseProposalMetadata {
   saltHex?: string;
   requiredSignatures?: number;
   /**
-   * Base64-serialized Miden `ChainAnchor` at the block the proposal's
-   * transaction summary binds, the proposer's sync height when it built the
-   * request. Required, and checked against the summary's block commitment: a
-   * rebuild binds the block it names. The proposal executes at the chain tip,
-   * not at the anchor; 0.18.0-rc.1 clients still re-execute at it.
+   * The block the proposal's transaction summary binds: the proposer's sync
+   * height when it built the request, or the block a custom producer's request
+   * names. Not signed: this SDK reads the block from the summary and refuses a
+   * proposal whose value disagrees (`BoundBlockMismatchError`), as the Rust SDK
+   * does. Every proposal this SDK creates writes it.
+   */
+  boundBlockNum?: number;
+  /**
+   * Legacy: the base64 Miden `ChainAnchor` 0.18 clients wrote instead of
+   * `boundBlockNum`. This SDK never sets or reads it; the codec passes it
+   * through so an old proposal exports and imports unchanged.
    */
   chainAnchor?: string;
 }

package/src/utils/eip712.ts

@@ -1,17 +1,38 @@
 import { keccak_256 } from '@noble/hashes/sha3.js';
+import type { SessionGrantFields } from '@openzeppelin/guardian-client';
 import { bytesToHex, hexToBytes } from './encoding.js';
+import { SESSION_GRANT_SCOPE, formatUtcSeconds } from '../session/grant.js';
 
 type TypedField = { name: string; type: string };
+
+/**
+ * EIP-712 typed data over `string`, `bytes`, `bytes32` and `uint64` fields,
+ * as Guardian signs it. Integers are decimal strings, as wallets accept them.
+ */
+export interface GuardianTypedData {
+  types: Record<string, TypedField[]>;
+  primaryType: string;
+  domain: { name: string; version: string };
+  message: Record<string, string>;
+}
+
 const EIP191_PREFIX = 0x19;
 const EIP712_VERSION = 0x01;
 const DOMAIN_VERSION = '1';
+const SESSION_DOMAIN_NAME = 'Guardian Session';
+const UINT64_MAX = 0xffffffffffffffffn;
 
 const domainFields: TypedField[] = [
   { name: 'name', type: 'string' },
   { name: 'version', type: 'string' },
 ];
 
-function typedData(name: string, primaryType: string, fieldName: string, value: string) {
+function typedData(
+  name: string,
+  primaryType: string,
+  fieldName: string,
+  value: string,
+): GuardianTypedData {
   return {
     types: {
       EIP712Domain: domainFields,
@@ -39,16 +60,115 @@ export function guardianKeyDiscoveryTypedData(challenge: Uint8Array) {
   return typedData('Guardian Key Discovery', 'GuardianKeyDiscovery', 'challenge', bytesToHex(challenge));
 }
 
-export function typedDataDigest(data: ReturnType<typeof typedData>): Uint8Array {
-  const domainType = new TextEncoder().encode('EIP712Domain(string name,string version)');
-  const primaryType = new TextEncoder().encode(`${data.primaryType}(bytes32 ${Object.keys(data.message)[0]})`);
+/**
+ * Readable session grant: every value Guardian binds is a top-level member,
+ * so the wallet displays the signer, the delegated key, the website, the
+ * lifetime (with a readable expiry), the scope, the Guardian key and the
+ * network instead of a hash.
+ */
+export function guardianSessionTypedData(grant: SessionGrantFields): GuardianTypedData {
+  return {
+    types: {
+      EIP712Domain: domainFields,
+      GuardianSession: [
+        { name: 'signer', type: 'bytes32' },
+        { name: 'sessionKey', type: 'bytes' },
+        { name: 'origin', type: 'string' },
+        { name: 'issuedAt', type: 'uint64' },
+        { name: 'expiresAt', type: 'uint64' },
+        { name: 'expires', type: 'string' },
+        { name: 'scope', type: 'string' },
+        { name: 'guardianKey', type: 'bytes32' },
+        { name: 'network', type: 'string' },
+      ],
+    },
+    primaryType: 'GuardianSession',
+    domain: { name: SESSION_DOMAIN_NAME, version: DOMAIN_VERSION },
+    message: {
+      signer: grant.signerCommitment,
+      sessionKey: grant.sessionPublicKey,
+      origin: grant.origin,
+      issuedAt: String(grant.issuedAt),
+      expiresAt: String(grant.expiresAt),
+      expires: formatUtcSeconds(grant.expiresAt),
+      scope: SESSION_GRANT_SCOPE,
+      guardianKey: grant.guardianCommitment,
+      network: grant.network,
+    },
+  };
+}
+
+/**
+ * Readable revoke-all: the signer whose sessions end and the request
+ * timestamp in milliseconds.
+ */
+export function guardianSessionRevokeAllTypedData(
+  signerCommitment: string,
+  timestampMs: number,
+): GuardianTypedData {
+  if (!Number.isInteger(timestampMs) || timestampMs < 0) {
+    throw new Error('Revoke-all timestamp must be a non-negative integer');
+  }
+  return {
+    types: {
+      EIP712Domain: domainFields,
+      GuardianSessionRevokeAll: [
+        { name: 'signer', type: 'bytes32' },
+        { name: 'timestamp', type: 'uint64' },
+      ],
+    },
+    primaryType: 'GuardianSessionRevokeAll',
+    domain: { name: SESSION_DOMAIN_NAME, version: DOMAIN_VERSION },
+    message: { signer: signerCommitment, timestamp: String(timestampMs) },
+  };
+}
+
+function encodeField(field: TypedField, value: string): Uint8Array {
+  switch (field.type) {
+    case 'string':
+      return keccak_256(new TextEncoder().encode(value));
+    case 'bytes':
+      return keccak_256(hexToBytes(value));
+    case 'bytes32': {
+      const bytes = hexToBytes(value);
+      if (bytes.length !== 32) {
+        throw new Error(`EIP-712 field ${field.name} must be 32 bytes`);
+      }
+      return bytes;
+    }
+    case 'uint64': {
+      let remaining = BigInt(value);
+      if (remaining < 0n || remaining > UINT64_MAX) {
+        throw new Error(`EIP-712 field ${field.name} must fit in uint64`);
+      }
+      const bytes = new Uint8Array(32);
+      for (let i = 31; i >= 24; i -= 1) {
+        bytes[i] = Number(remaining & 0xffn);
+        remaining >>= 8n;
+      }
+      return bytes;
+    }
+    default:
+      throw new Error(`Unsupported EIP-712 field type: ${field.type}`);
+  }
+}
+
+export function typedDataDigest(data: GuardianTypedData): Uint8Array {
+  const encoder = new TextEncoder();
+  const fields = data.types[data.primaryType];
+  const typeString = `${data.primaryType}(${fields.map((f) => `${f.type} ${f.name}`).join(',')})`;
+
   const domain = new Uint8Array(96);
-  domain.set(keccak_256(domainType));
-  domain.set(keccak_256(new TextEncoder().encode(data.domain.name)), 32);
-  domain.set(keccak_256(new TextEncoder().encode(data.domain.version)), 64);
-  const struct = new Uint8Array(64);
-  struct.set(keccak_256(primaryType));
-  struct.set(hexToBytes(Object.values(data.message)[0]), 32);
+  domain.set(keccak_256(encoder.encode('EIP712Domain(string name,string version)')));
+  domain.set(keccak_256(encoder.encode(data.domain.name)), 32);
+  domain.set(keccak_256(encoder.encode(data.domain.version)), 64);
+
+  const struct = new Uint8Array(32 * (fields.length + 1));
+  struct.set(keccak_256(encoder.encode(typeString)));
+  fields.forEach((field, index) => {
+    struct.set(encodeField(field, data.message[field.name]), 32 * (index + 1));
+  });
+
   const preimage = new Uint8Array(66);
   preimage.set([EIP191_PREFIX, EIP712_VERSION]);
   preimage.set(keccak_256(domain), 2);

package/src/utils/felt.ts

@@ -1,4 +1,4 @@
-import { Felt } from '@miden-sdk/miden-sdk';
+import { Felt, FeltArray, Rpo256, type Word } from '@miden-sdk/miden-sdk';
 
 /**
  * Goldilocks field order (`2^64 - 2^32 + 1`), matching `Felt::ORDER` in
@@ -18,3 +18,21 @@ const FELT_ORDER = 18446744069414584321n;
 export function feltFromU64Reduced(value: bigint): Felt {
   return new Felt(BigInt.asUintN(64, value) % FELT_ORDER);
 }
+
+/**
+ * RPO hash of `bytes` packed as 8-byte little-endian chunks (the last one
+ * zero-padded), mirroring `guardian_shared::felt::domain_tag_word`. The
+ * convention every Guardian message domain tag uses.
+ */
+export function domainTagWord(bytes: Uint8Array): Word {
+  const felts: Felt[] = [];
+  for (let offset = 0; offset < bytes.length; offset += 8) {
+    let value = 0n;
+    for (let i = 0; i < 8; i += 1) {
+      const byte = offset + i < bytes.length ? bytes[offset + i] : 0;
+      value |= BigInt(byte) << BigInt(8 * i);
+    }
+    felts.push(feltFromU64Reduced(value));
+  }
+  return Rpo256.hashElements(new FeltArray(felts));
+}