@layerzerolabs/common-canton 0.2.110 → 0.2.112

package/src/events.ts

@@ -1,37 +1,8 @@
-import { buildTransactionWithResultSchema } from '@layerzerolabs/common-chain-model';
-import { NonRetryableError } from '@layerzerolabs/common-error-utils';
+import { NonEmittableError } from '@layerzerolabs/common-error-utils';
 
 import type { CantonTransaction, ICantonClient } from './client';
-import type { CreatedEvent } from './open-api/models';
-import { cantonTransactionSchema } from './transaction';
-
-const cantonTxWithResultSchema = buildTransactionWithResultSchema(cantonTransactionSchema);
-
-// TODO(canton): confirm these poll values are enough to wait for archival across environments.
-const REQUEST_ARCHIVAL_POLL_INTERVAL_MS = 2000;
-const REQUEST_ARCHIVAL_MAX_ATTEMPTS = 60;
-
-// IRequest interface choices that consume the Request contract via `archive reqCid` in their impls.
-const IREQUEST_ACCEPT_CHOICE = 'IRequest_Accept';
-const IREQUEST_REJECT_CHOICE = 'IRequest_Reject';
-
-const REQUEST_TEMPLATE_QUALIFIED_NAME = 'Request:Request';
-
-/**
- * Fetches a transaction by updateId and returns all CreatedEvents.
- */
-export const fetchCreatedEvents = async (
-    client: ICantonClient,
-    updateId: string,
-    parties: string[],
-): Promise<CreatedEvent[]> => {
-    const cantonTx = await client.fetchTransactionByUpdateId(updateId, parties);
-    return (
-        cantonTx.events
-            ?.filter((event): event is { CreatedEvent: CreatedEvent } => 'CreatedEvent' in event)
-            .map((event) => event.CreatedEvent) ?? []
-    );
-};
+import type { CreatedEvent, ExercisedEvent } from './open-api/models';
+import { cantonTransactionWithResultSchema } from './transaction';
 
 /**
  * Finds a CreatedEvent matching the expected templateId whose signatories
@@ -50,6 +21,22 @@ export const findMatchingCreatedEvent = (
     });
 };
 
+/**
+ * Fetches a transaction by updateId and returns all CreatedEvents.
+ */
+export const fetchCreatedEvents = async (
+    client: ICantonClient,
+    updateId: string,
+    parties: string[],
+): Promise<CreatedEvent[]> => {
+    const cantonTx = await client.fetchTransactionByUpdateId(updateId, parties);
+    return (
+        cantonTx.events
+            ?.filter((event): event is { CreatedEvent: CreatedEvent } => 'CreatedEvent' in event)
+            .map((event) => event.CreatedEvent) ?? []
+    );
+};
+
 /**
  * Parses a Canton transaction-with-result, fetches the created events from the ledger,
  * and returns the first CreatedEvent matching the submitted command's templateId and actAs
@@ -59,7 +46,7 @@ export const findMatchingCreatedEventFromTx = async (
     client: ICantonClient,
     tx: unknown,
 ): Promise<CreatedEvent | null> => {
-    const parsed = cantonTxWithResultSchema.safeParse(tx);
+    const parsed = cantonTransactionWithResultSchema.safeParse(tx);
     if (!parsed.success) return null;
 
     if (parsed.data.result.type !== 'success') return null;
@@ -93,142 +80,31 @@ export const cantonDeploymentSucceeded = async (
 };
 
 /**
- * Success check for register-style deploys (an exercise on Uln302 that creates a
- * Request, which the validator then accepts or rejects in a later transaction).
- *
- * Positively confirms acceptance: locate the Request created by this submission,
- * then delegate to waitForRequestArchival, which waits for the Request to be
- * archived and verifies the IRequest_Accept choice ran (throwing on reject,
- * unexpected archival, or timeout). This is a positive accept check rather than
- * inferring success from the absence of a rejection event.
- */
-export const cantonRegisterSucceeded = async (
-    client: ICantonClient,
-    txWithResult: unknown,
-): Promise<boolean> => {
-    const parsed = cantonTxWithResultSchema.safeParse(txWithResult);
-    if (!parsed.success || parsed.data.result.type !== 'success') return false;
-
-    const updateId = parsed.data.result.minedTxHash;
-    if (!updateId) return false;
-
-    // Deferred-sender register payloads build with empty actAs (the sender is
-    // resolved at sign time), so fall back to the parties this user can read as.
-    const { actAs } = parsed.data.populatedTransaction;
-    const parties = actAs.length ? actAs : await client.listUserParties();
-    if (!parties.length) return false;
-
-    const createdEvents = await fetchCreatedEvents(client, updateId, parties);
-    const requestEvent = createdEvents.find((event) =>
-        event.templateId?.includes(REQUEST_TEMPLATE_QUALIFIED_NAME),
-    );
-    if (!requestEvent) return false;
-
-    try {
-        await waitForRequestArchival(client, requestEvent.contractId, parties);
-        return true;
-    } catch {
-        return false;
-    }
-};
-
-/**
- * Poll until `contractId` is archived, then return the transaction tree that
- * archived it. Generic: knows nothing about which choice did the archiving.
- * Throws NonRetryableError on timeout.
+ * Waits for a contract to be archived and returns the transaction that archived it.
+ * Throws NonEmittableError if the contract is not yet archived.
  */
 export const waitForArchival = async (
     client: ICantonClient,
     contractId: string,
     parties: string[],
 ): Promise<CantonTransaction> => {
-    for (let attempt = 1; attempt <= REQUEST_ARCHIVAL_MAX_ATTEMPTS; attempt++) {
-        const { archived } = await client.fetchEventsByContractId(contractId, parties);
-        if (archived) {
-            return client.fetchTransactionByOffset(archived.offset, parties);
-        }
-        // Skip the sleep on the final attempt — there's no next iteration to wait for.
-        if (attempt < REQUEST_ARCHIVAL_MAX_ATTEMPTS) {
-            await new Promise((resolve) => setTimeout(resolve, REQUEST_ARCHIVAL_POLL_INTERVAL_MS));
-        }
+    const { archived } = await client.fetchEventsByContractId(contractId, parties);
+    if (archived) {
+        return client.fetchTransactionByOffset(archived.offset, parties);
     }
-    throw new NonRetryableError(
-        `Archival timeout (${REQUEST_ARCHIVAL_MAX_ATTEMPTS} attempts) for ${contractId}`,
-    );
-};
-
-/**
- * Return the argument of the first exercise of `choice` on `contractId` in a
- * transaction tree, typed as the caller expects. Generic over choice and arg
- * type; returns undefined when no such exercise is present.
- */
-export const getExercisedChoiceArgument = <TArg = unknown>(
-    transaction: CantonTransaction,
-    contractId: string,
-    choice: string,
-): TArg | undefined => {
-    for (const event of transaction.events ?? []) {
-        if (!('ExercisedEvent' in event)) continue;
-        const { ExercisedEvent: exercised } = event;
-        if (exercised.contractId === contractId && exercised.choice === choice) {
-            return exercised.choiceArgument as TArg;
-        }
-    }
-    return undefined;
-};
-
-/**
- * Wait for a Request to be archived and confirm it was accepted, returning the
- * IRequest_Accept choice argument typed as `TAccept` (callers pass the codegen
- * `IRequest_Accept` type to get `acceptContext` typed).
- *
- * IRequest_Accept and IRequest_Reject both end with `archive reqCid` in their
- * Daml impls, so the archive alone can't distinguish them — the choice is read
- * off the archive transaction tree. Throws NonRetryableError on rejection, on
- * archival via any other choice (unexpected), or on timeout.
- */
-export const waitForRequestArchival = async <TAccept = unknown>(
-    client: ICantonClient,
-    requestContractId: string,
-    parties: string[],
-): Promise<TAccept> => {
-    const transaction = await waitForArchival(client, requestContractId, parties);
-
-    const accept = getExercisedChoiceArgument<TAccept>(
-        transaction,
-        requestContractId,
-        IREQUEST_ACCEPT_CHOICE,
-    );
-    if (accept !== undefined) return accept;
-
-    const reject = getExercisedChoiceArgument<{ rejectContext?: unknown }>(
-        transaction,
-        requestContractId,
-        IREQUEST_REJECT_CHOICE,
-    );
-    if (reject !== undefined) {
-        const reason = reject.rejectContext
-            ? JSON.stringify(reject.rejectContext).slice(0, 500)
-            : 'unknown';
-        throw new NonRetryableError(`Request rejected — rejectContext: ${reason}`);
-    }
-
-    const consuming = getConsumingChoice(transaction, requestContractId);
-    throw new NonRetryableError(
-        `Request ${requestContractId} archived via unexpected choice ${consuming ?? '<none>'}`,
-    );
+    throw new NonEmittableError(`Contract ${contractId} is not archived yet`);
 };
 
-/** Name of the consuming exercise on `contractId` in a transaction tree, if any. */
-const getConsumingChoice = (
+/** Returns the first exercised event on `contractId` in a transaction tree, if any. */
+export const getExercisedEvent = (
     transaction: CantonTransaction,
     contractId: string,
-): string | undefined => {
+): ExercisedEvent | undefined => {
     for (const event of transaction.events ?? []) {
         if (!('ExercisedEvent' in event)) continue;
         const { ExercisedEvent: exercised } = event;
-        if (exercised.contractId === contractId && exercised.consuming) {
-            return exercised.choice;
+        if (exercised.contractId === contractId) {
+            return exercised;
         }
     }
     return undefined;

package/src/index.ts

@@ -1,4 +1,7 @@
+export * from './amulet';
 export * from './auth';
+export * from './crypto';
+export * from './daml-serde';
 export * from './deferredValue';
 export * from './events';
 export * from './provider';

package/src/provider.ts

@@ -14,66 +14,49 @@ import { Configuration } from './open-api/runtime';
 // ─────────────────────────────────────────────────────────────────────────────
 
 /**
- * Composite provider for Canton — bundles both transport layers and shared auth.
- *
  * - {@link client} — JSON Ledger API (commands, queries, updates)
  * - {@link grpcClient} — gRPC Admin API (topology transactions, namespace queries)
  * - {@link tokenProvider} — Shared Bearer-token source used by both transports
+ * - {@link walletUrl} — Canton Network validator wallet (scan-proxy CIP-56 endpoints)
  */
-export type CantonProvider = {
+export type CantonChainProvider = {
     client: ICantonClient;
     grpcClient: CantonGrpcClient;
     tokenProvider: TokenProvider;
     /** Validator wallet URL for scan-proxy CIP-56 endpoints. Required. */
     walletUrl: string;
-    /** LayerZero sequencer base URL (e.g. "http://localhost:8080"); vApp JSON-RPC at `/vapp`. Required. */
-    sequencerUrl: string;
-    /** Sequencer validator pubkeys plus quorum for verifying signed read responses. */
-    sequencerCommittee?: SequencerCommittee;
-};
-
-/**
- * Client-side committee config for secp256k1 sequencer read verification.
- * Pubkeys must be hex-encoded with `0x` prefix in the same format returned by
- * `recoverSecp256k1PublicKey`.
- */
-export type SequencerCommittee = {
-    publicKeys: `0x${string}`[];
-    quorum: number;
 };
 
 // ─────────────────────────────────────────────────────────────────────────────
 // URI Parsing
 // ─────────────────────────────────────────────────────────────────────────────
 
-export type CantonUriParams = {
+export type CantonChainUriParams = {
     /** Base URL of the JSON Ledger API (e.g. "http://localhost:5975") */
     jsonApiUrl: string;
     /** Host:port of the gRPC Admin API (e.g. "localhost:5076") */
     adminApiHost: string;
     /** Ledger API user ID (default: "participant_admin") */
     userId: string;
+    /** Parties granted `actAs` on localnet tokens (comma-separated in the URI). */
+    actAs: string[];
     /** Validator wallet URL for scan-proxy CIP-56 endpoints (e.g. "http://localhost:7201"). Required. */
     walletUrl: string;
-    /** LayerZero sequencer base URL (e.g. "http://localhost:8080"); vApp JSON-RPC at `/vapp`. Required. */
-    sequencerUrl: string;
-    /** Sequencer committee config parsed from the provider URI. */
-    sequencerCommittee?: SequencerCommittee;
     /** OAuth2 client credentials config — present only for non-local environments */
     oauth2?: ClientCredentialsTokenProviderConfig;
 };
 
 /**
- * Parse a Canton provider URI into its constituent parts.
+ * Parse a Canton chain provider URI into its constituent parts.
  *
  * URI format:
- *   `<json-api-base>?admin-api=<host:port>&user-id=<id>[&token-url=...&client-id=...&client-secret=...&scope=...&audience=...]`
+ *   `<json-api-base>?admin-api=<host:port>&user-id=<id>&wallet-url=<url>[&token-url=...&client-id=...&client-secret=...&scope=...&audience=...]`
  *
  * The base URL (everything before the query string) is the JSON Ledger API endpoint.
  * Canton-specific params are extracted and removed; any remaining query params are
  * preserved on the JSON API URL.
  */
-export function parseCantonUri(uri: string): CantonUriParams {
+export function parseCantonChainUri(uri: string): CantonChainUriParams {
     const url = new URL(uri);
 
     const adminApiHost = url.searchParams.get('admin-api');
@@ -82,26 +65,26 @@ export function parseCantonUri(uri: string): CantonUriParams {
     }
 
     const userId = url.searchParams.get('user-id') ?? 'participant_admin';
+    const actAsParam = url.searchParams.get('act-as');
+    const actAs =
+        actAsParam
+            ?.split(',')
+            .map((party) => party.trim())
+            .filter((party) => party.length > 0) ?? [];
     const walletUrl = url.searchParams.get('wallet-url');
     if (!walletUrl) {
         throw new Error('Canton provider URI missing required "wallet-url" query parameter');
     }
-    const sequencerUrl = url.searchParams.get('sequencer-url');
-    if (!sequencerUrl) {
-        throw new Error('Canton provider URI missing required "sequencer-url" query parameter');
-    }
-    const sequencerValidatorsParam = url.searchParams.get('sequencer-validators');
-    const sequencerQuorumParam = url.searchParams.get('sequencer-quorum');
     const tokenUrl = url.searchParams.get('token-url') ?? undefined;
     const clientId = url.searchParams.get('client-id') ?? undefined;
     const clientSecret = url.searchParams.get('client-secret') ?? undefined;
     const scope = url.searchParams.get('scope') ?? undefined;
     const audience = url.searchParams.get('audience') ?? undefined;
 
-    // Remove Canton params to get clean JSON API URL
     for (const key of [
         'admin-api',
         'user-id',
+        'act-as',
         'wallet-url',
         'sequencer-url',
         'sequencer-validators',
@@ -115,46 +98,6 @@ export function parseCantonUri(uri: string): CantonUriParams {
         url.searchParams.delete(key);
     }
 
-    let sequencerCommittee: SequencerCommittee | undefined;
-    if (sequencerValidatorsParam !== null && sequencerQuorumParam !== null) {
-        const publicKeys = sequencerValidatorsParam
-            .split(',')
-            .map((s) => s.trim().toLowerCase())
-            .filter((s) => s.length > 0);
-        if (publicKeys.length === 0) {
-            throw new Error(
-                'Canton provider URI sequencer-validators must contain at least one pubkey',
-            );
-        }
-        for (const publicKey of publicKeys) {
-            if (!publicKey.startsWith('0x')) {
-                throw new Error(
-                    `Canton provider URI sequencer-validators pubkey must start with 0x, got: ${publicKey.slice(0, 10)}...`,
-                );
-            }
-        }
-
-        const quorum = Number(sequencerQuorumParam);
-        if (!Number.isInteger(quorum) || quorum < 1) {
-            throw new Error(
-                `Canton provider URI sequencer-quorum must be a positive integer, got: ${sequencerQuorumParam}`,
-            );
-        }
-        if (quorum > publicKeys.length) {
-            throw new Error(
-                `Canton provider URI sequencer-quorum=${quorum} exceeds committee size ${publicKeys.length}`,
-            );
-        }
-        sequencerCommittee = {
-            publicKeys: publicKeys as `0x${string}`[],
-            quorum,
-        };
-    } else if (sequencerValidatorsParam !== null || sequencerQuorumParam !== null) {
-        throw new Error(
-            'Canton provider URI must set both sequencer-validators and sequencer-quorum together',
-        );
-    }
-
     const jsonApiUrl = url.toString().replace(/\/$/, '');
 
     const oauth2 =
@@ -166,9 +109,8 @@ export function parseCantonUri(uri: string): CantonUriParams {
         jsonApiUrl,
         adminApiHost,
         userId,
+        actAs,
         walletUrl,
-        sequencerUrl,
-        sequencerCommittee,
         oauth2,
     };
 }
@@ -177,7 +119,7 @@ export function parseCantonUri(uri: string): CantonUriParams {
 // Provider Factory
 // ─────────────────────────────────────────────────────────────────────────────
 
-export type CreateCantonProviderOptions = {
+export type CreateCantonChainProviderOptions = {
     /** Raw provider URI (from provider config) */
     uri: string;
     /** When true, uses LocalTokenProvider (self-signed JWTs) instead of OAuth2 */
@@ -185,17 +127,17 @@ export type CreateCantonProviderOptions = {
 };
 
 /**
- * Create a {@link CantonProvider} from a provider URI.
+ * Create a {@link CantonChainProvider} from a provider URI.
  *
  * - **isLocal=true**: Uses {@link LocalTokenProvider} with admin-level access (self-signed JWTs).
  * - **isLocal=false**: Uses {@link ClientCredentialsTokenProvider} with OAuth2 client
  *   credentials extracted from the URI query parameters.
  */
-export function createCantonProvider({
+export function createCantonChainProvider({
     uri,
     isLocal,
-}: CreateCantonProviderOptions): CantonProvider {
-    const params = parseCantonUri(uri);
+}: CreateCantonChainProviderOptions): CantonChainProvider {
+    const params = parseCantonChainUri(uri);
 
     const tokenProvider = createTokenProvider(params, isLocal);
 
@@ -217,12 +159,10 @@ export function createCantonProvider({
         grpcClient,
         tokenProvider,
         walletUrl: params.walletUrl,
-        sequencerUrl: params.sequencerUrl,
-        sequencerCommittee: params.sequencerCommittee,
     };
 }
 
-function createTokenProvider(params: CantonUriParams, isLocal: boolean): TokenProvider {
+function createTokenProvider(params: CantonChainUriParams, isLocal: boolean): TokenProvider {
     if (isLocal) {
         return new LocalTokenProvider({
             userId: params.userId,

package/src/sdk/canton-sdk.ts

@@ -452,6 +452,19 @@ export class CantonSdk {
         return this.#client.queryActiveContractsByParties(parties, offset, templateIds, opts);
     }
 
+    /**
+     * Query active contracts visible to any of the given parties that implement
+     * the given interfaces (single API call).
+     */
+    queryActiveContractsByInterface(
+        parties: string[],
+        offset: number,
+        interfaceIds: string[],
+        opts?: { limit?: number },
+    ): Promise<JsActiveContract[]> {
+        return this.#client.queryActiveContractsByInterface(parties, offset, interfaceIds, opts);
+    }
+
     /**
      * Query active contracts visible to any of the given parties, deduplicated by contractId.
      * Returns normalized contracts (flat shape). Use when you need a merged view across multiple parties.

package/src/transaction.ts

@@ -2,6 +2,7 @@ import { z } from 'zod';
 
 import {
     assignedTransactionSchema,
+    buildTransactionWithResultSchema,
     minedTransactionSchema,
     signedTransactionSchema,
     transactionSchema,
@@ -71,6 +72,9 @@ export const cantonTransactionSchema = transactionSchema.extend({
     }),
 });
 
+export const cantonTransactionWithResultSchema =
+    buildTransactionWithResultSchema(cantonTransactionSchema);
+
 const cantonInflightTransactionSchema = z.object({
     /** The prepared transaction blob */
     preparedTransaction: z.string(),

package/test/crypto.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+    derEncodeSignature,
+    publicKeyToSpkiDer,
+    SECP256K1_SPKI_DER_HEADER,
+    SECP256K1_SPKI_DER_HEADER_HEX,
+} from '../src/crypto';
+
+// A throwaway uncompressed secp256k1 public key shape (0x04 ‖ X ‖ Y, 65 bytes).
+const UNCOMPRESSED_KEY = `04${'ab'.repeat(64)}`;
+
+describe('SECP256K1_SPKI_DER_HEADER', () => {
+    it('is the canonical 23-byte secp256k1 SPKI-DER header', () => {
+        expect(SECP256K1_SPKI_DER_HEADER).toHaveLength(23);
+        expect(SECP256K1_SPKI_DER_HEADER_HEX).toBe(
+            '3056301006072a8648ce3d020106052b8104000a034200',
+        );
+        expect(SECP256K1_SPKI_DER_HEADER_HEX).toHaveLength(46);
+    });
+});
+
+describe('publicKeyToSpkiDer', () => {
+    it('prepends the SPKI-DER header to the uncompressed key body', () => {
+        const spki = publicKeyToSpkiDer(`0x${UNCOMPRESSED_KEY}`);
+        expect(spki).toBe(SECP256K1_SPKI_DER_HEADER_HEX + UNCOMPRESSED_KEY);
+        expect(spki).toHaveLength(46 + 130);
+    });
+
+    it('lowercases and tolerates a missing 0x prefix', () => {
+        expect(publicKeyToSpkiDer(UNCOMPRESSED_KEY.toUpperCase())).toBe(
+            SECP256K1_SPKI_DER_HEADER_HEX + UNCOMPRESSED_KEY,
+        );
+    });
+
+    it('rejects a non-uncompressed (wrong-length or non-0x04) key', () => {
+        expect(() => publicKeyToSpkiDer('0x02abcd')).toThrow();
+        expect(() => publicKeyToSpkiDer(`03${'ab'.repeat(64)}`)).toThrow();
+    });
+});
+
+describe('derEncodeSignature', () => {
+    it('DER-encodes (r, s) as SEQUENCE { INTEGER r, INTEGER s } with minimal integers', () => {
+        // r = 1, s = 2 → 30 06 02 01 01 02 01 02
+        expect(derEncodeSignature('01', '02')).toBe('3006020101020102');
+    });
+
+    it('prepends 0x00 to an integer whose high bit is set', () => {
+        // r = 0xff (high bit set, needs a leading 0x00), s = 1
+        expect(derEncodeSignature('ff', '01')).toBe('3007020200ff020101');
+    });
+});

package/test/daml-serde.test.ts

@@ -0,0 +1,140 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+    assertHexLength,
+    codePointLength,
+    formatDamlDecimal,
+    IntLikeSchema,
+    intToHex,
+    keccak256Hex,
+    padLeft,
+    showBool,
+    showInt,
+    textToHex,
+    timeToUnixSeconds,
+    toBigInt,
+} from '../src/daml-serde';
+
+describe('toBigInt', () => {
+    it('passes through bigints and converts safe-integer numbers', () => {
+        expect(toBigInt(5)).toBe(5n);
+        expect(toBigInt(7n)).toBe(7n);
+    });
+
+    it('rejects unsafe-integer numbers', () => {
+        expect(() => toBigInt(2 ** 53)).toThrow(/safe integer/);
+    });
+});
+
+describe('IntLikeSchema', () => {
+    it('accepts bigints and safe-integer numbers (incl. negatives)', () => {
+        expect(IntLikeSchema.parse(5)).toBe(5);
+        expect(IntLikeSchema.parse(-5)).toBe(-5);
+        expect(IntLikeSchema.parse(2n ** 64n)).toBe(2n ** 64n);
+    });
+
+    it('rejects unsafe-integer numbers (must use a bigint)', () => {
+        expect(IntLikeSchema.safeParse(2 ** 53).success).toBe(false);
+    });
+});
+
+describe('textToHex', () => {
+    it('encodes ASCII two hex digits per char', () => {
+        expect(textToHex('01')).toBe('3031');
+        expect(textToHex('setSeed')).toBe('73657453656564');
+    });
+
+    it('rejects non-ASCII code points', () => {
+        expect(() => textToHex('café')).toThrow(/Non-ASCII/);
+    });
+});
+
+describe('intToHex', () => {
+    it('is minimal and lowercase', () => {
+        expect(intToHex(0)).toBe('0');
+        expect(intToHex(255)).toBe('ff');
+        expect(intToHex(2n ** 63n - 1n)).toBe('7fffffffffffffff');
+    });
+
+    it('rejects negative values', () => {
+        expect(() => intToHex(-1)).toThrow(/negative/);
+    });
+});
+
+describe('padLeft', () => {
+    it('left-pads with zeros and rejects oversize values', () => {
+        expect(padLeft(16, '15180')).toBe('0000000000015180');
+        expect(() => padLeft(2, 'abc')).toThrow(/exceeds pad width/);
+    });
+});
+
+describe('assertHexLength', () => {
+    it('returns stripped lowercase hex of the exact length', () => {
+        expect(assertHexLength(4, '0xABcd')).toBe('abcd');
+    });
+
+    it('rejects wrong length, odd length, and non-hex', () => {
+        expect(() => assertHexLength(4, 'abc')).toThrow();
+        expect(() => assertHexLength(4, 'abcde')).toThrow();
+        expect(() => assertHexLength(4, 'zzzz')).toThrow();
+    });
+});
+
+describe('show helpers', () => {
+    it('showBool capitalizes like DAML', () => {
+        expect(showBool(true)).toBe('True');
+        expect(showBool(false)).toBe('False');
+    });
+
+    it('showInt is base-10', () => {
+        expect(showInt(0)).toBe('0');
+        expect(showInt(-5)).toBe('-5');
+        expect(showInt(123n)).toBe('123');
+    });
+});
+
+describe('formatDamlDecimal', () => {
+    it('keeps at least one fractional digit and strips trailing zeros', () => {
+        expect(formatDamlDecimal('1.50')).toBe('1.5');
+        expect(formatDamlDecimal('100')).toBe('100.0');
+        expect(formatDamlDecimal('0')).toBe('0.0');
+        expect(formatDamlDecimal('-1.5')).toBe('-1.5');
+    });
+
+    it('rejects more than 10 fractional digits and exponent notation', () => {
+        expect(() => formatDamlDecimal('0.123456789012')).toThrow();
+        expect(() => formatDamlDecimal(1e-12)).toThrow();
+    });
+});
+
+describe('keccak256Hex', () => {
+    it('hashes the bytes denoted by the hex string', () => {
+        // keccak256 of the empty byte string.
+        expect(keccak256Hex('')).toBe(
+            'c5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470',
+        );
+        // keccak256 of the single byte 0x00.
+        expect(keccak256Hex('00')).toBe(
+            'bc36789e7a1e281436464229828f817d6612f7b477d66591ff96a9e064bcc98a',
+        );
+    });
+
+    it('rejects malformed hex rather than hashing raw text', () => {
+        expect(() => keccak256Hex('xyz')).toThrow(/valid hex/);
+        expect(() => keccak256Hex('abc')).toThrow(/valid hex/);
+    });
+});
+
+describe('codePointLength', () => {
+    it('counts Unicode code points', () => {
+        expect(codePointLength('alice')).toBe(5);
+        expect(codePointLength('𝔸')).toBe(1);
+    });
+});
+
+describe('timeToUnixSeconds', () => {
+    it('returns whole seconds since the unix epoch', () => {
+        expect(timeToUnixSeconds(new Date('1970-01-01T00:00:01.000Z'))).toBe(1n);
+        expect(timeToUnixSeconds(new Date('2021-01-01T00:00:00.000Z'))).toBe(1609459200n);
+    });
+});