@ottochain/sdk 2.2.5 → 2.4.0

package/dist/types/index.d.ts

@@ -17,16 +17,22 @@
  */
 export * from '@constellation-network/metagraph-sdk';
 export { verify } from './verify.js';
+export { signDataUpdate, createSignedObject, addSignature, batchSign } from './signing.js';
 export { MetagraphClient, createMetagraphClient, HttpClient, NetworkError as MetagraphNetworkError, } from '@constellation-network/metagraph-sdk/network';
 export type { MetagraphClientConfig as BaseMetagraphClientConfig, LayerType, ClusterInfo, } from '@constellation-network/metagraph-sdk/network';
 export type { RequestOptions, TransactionStatus, PendingTransaction, PostTransactionResponse, EstimateFeeResponse, PostDataResponse, } from '@constellation-network/metagraph-sdk/network';
 export * from './types.js';
 export * from './ottochain/transaction.js';
-export { normalizeCreateStateMachine, normalizeTransitionStateMachine, normalizeArchiveStateMachine, normalizeMessage } from './ottochain/normalize.js';
 export { dropNulls } from './ottochain/drop-nulls.js';
+export { buildGenesisManifest, GENESIS_MANIFEST_VERSION } from './ottochain/genesis-manifest.js';
+export type { GenesisManifest, GenesisPackage, GenesisMachineShape, GenesisMessageShape, GenesisFieldShape, GenesisStateMachineDefinition, } from './ottochain/index.js';
 export * from './generated/index.js';
 export { OttoChainError, NetworkError, ValidationError, SigningError, TransactionError, ErrorCode, isErrorCode, wrapError, } from './errors.js';
 export { DagAddressSchema, PrivateKeySchema, PublicKeySchema, KeyPairSchema, SignatureProofSchema, SignedSchema, TransactionReferenceSchema, CurrencyTransactionValueSchema, CurrencyTransactionSchema, TransferParamsSchema, AgentIdentityRegistrationSchema, PlatformLinkSchema, ContractTermsSchema, ProposeContractRequestSchema, AcceptContractRequestSchema, CompleteContractRequestSchema, validate, validatePrivateKey, validatePublicKey, validateAddress, validateKeyPair, safeParse, assert, type ValidatedKeyPair, type ValidatedSignatureProof, type ValidatedCurrencyTransaction, type ValidatedTransferParams, type ValidatedAgentIdentityRegistration, type ValidatedPlatformLink, type ValidatedProposeContractRequest, type ValidatedAcceptContractRequest, type ValidatedCompleteContractRequest, } from './validation.js';
 export { MetagraphClient as OttoMetagraphClient } from './ottochain/metagraph-client.js';
 export type { MetagraphClientConfig, Checkpoint, SubscribeOptions, FiberStateCallback, Unsubscribe, } from './ottochain/metagraph-client.js';
-export { toProtoDefinition, defineFiberApp, type ProtoStateMachineDefinition, type FiberAppDefinition, type FiberAppMetadata, type StateDefinition, type Transition, } from './schema/fiber-app.js';
+export { toProtoDefinition, defineFiberApp, type ProtoStateMachineDefinition, type FiberAppDefinition, type FiberAppMetadata, type StateDefinition, type StdStateMetadata, type StateCategory, type Transition, } from './schema/fiber-app.js';
+export { type GuardRule, signerIsParty, signerIsAnyParty, signerInSet, signerIsNotParty, signerHasEntry, assetSignerIs, actorIsSigner, actorInSet, actorHasEntry, signerHasReputation, signerHasRole, signerHasReputationVia, signerHasRoleVia, depInState, } from './schema/guards.js';
+export { addDependency, setDependencyActive } from './schema/effects.js';
+export { shieldApp, SHIELDED_POOL_STATE, type ShieldOptions } from './privacy/shield-app.js';
+export type { paths as ApiPaths, operations as ApiOperations, components as ApiComponents, VersionInfo, TransitionFeeEstimate, ScriptFeeEstimate, SubscribeRequest, SubscribeResponse, Subscriber, SubscriberList, } from './openapi.js';

package/dist/types/openapi.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Typed OttoChain HTTP API surface.
+ *
+ * These types are generated from the metagraph's OpenAPI contract
+ * (`openapi/ottochain-openapi.json`, emitted by ottochain's tapir `ApiEndpoints`) — so the SDK and the
+ * chain share ONE source of truth for request/response shapes, instead of reverse-engineering them inline.
+ *
+ * Regenerate after the contract changes with `pnpm gen:openapi`. The raw generated module is
+ * `src/generated/openapi.ts`; this file gives consumers stable, named aliases for the precise response
+ * DTOs. Heavy domain bodies (onchain, checkpoint, records, state proofs) are typed `unknown`/opaque in
+ * the contract for now — see ottochain `docs/proposals/typed-network-interface.md` §3.
+ */
+import type { components, operations, paths } from './generated/openapi.js';
+export type { components, operations, paths };
+type Schemas = components['schemas'];
+export type VersionInfo = Schemas['VersionInfo'];
+export type TransitionFeeEstimate = Schemas['TransitionFeeEstimate'];
+export type ScriptFeeEstimate = Schemas['ScriptFeeEstimate'];
+export type SubscribeRequest = Schemas['SubscribeRequest'];
+export type SubscribeResponse = Schemas['SubscribeResponse'];
+export type Subscriber = Schemas['Subscriber'];
+export type SubscriberList = Schemas['SubscriberList'];

package/dist/types/ottochain/genesis-manifest.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Genesis Manifest Exporter
+ *
+ * The ottochain metagraph can boot from a NON-EMPTY genesis: a set of standard
+ * packages pre-registered in the registry before any user transaction. This SDK
+ * is the source of truth for those std apps (their proto schemas + JSON-Logic
+ * state-machine definitions), so it is also the source of truth for the
+ * *genesis manifest* — the per-app CONTENT the chain needs to pre-register each
+ * package at genesis.
+ *
+ * DESIGN — content, not consensus hashes:
+ * The manifest ships CONTENT only: the `machineShape` (the typed, proto-faithful
+ * projection of the app's state message) and the `definition` (the JSON-Logic
+ * `StateMachineDefinition`, verbatim — the same object the chain decodes for any
+ * fiber). The CHAIN computes the consensus values itself from this content:
+ *   - `logicHash` = `StateMachineDefinition.computeDigest(definition)`
+ *   - `schemaHash` = commitment over the FileDescriptorSet (off-chain/Bridge)
+ * We deliberately do NOT replicate the chain's canonical hashing here, so there
+ * is ZERO hash-parity risk. No advisory hashes are emitted (see HONESTY notes in
+ * the PR description); add them later only if an off-chain consumer needs them,
+ * clearly marked advisory.
+ *
+ * NAMING — the reserved `std` label:
+ * Each package is named `std.<app>.package`. `RegistryName` reserves the `std`
+ * label in-protocol (`RegistryName.isReserved`), so ordinary user registrations
+ * of `std.*` are rejected — only the privileged genesis path may claim them.
+ * That is exactly the point: users cannot squat the standard names.
+ *
+ * SCHEMA SHAPES — chain-verified ground truth:
+ * The three `stateMessage` shapes are reproduced verbatim from the chain's own
+ * conformance suite (`StandardAppsConformanceSuite`, the `identity` / `proposal`
+ * / `market` `MessageShape` vals), which proves the on-chain shape validator and
+ * the conformance gate accept them. `commands` is left EMPTY for this first cut —
+ * the conformance suite itself models all three apps with `SortedMap.empty`
+ * commands, and the proto `*Request` messages are transaction-layer DTOs that do
+ * not map cleanly onto the universal state machines' free-form JSON-Logic event
+ * payloads. Deriving per-event command shapes is a flagged follow-up.
+ *
+ * The JSON shape emitted here is built to deserialize against the chain's circe
+ * codecs (`MachineShape` / `FieldShape` / `MessageShape` and
+ * `StateMachineDefinition`), whose magnolia config is camelCase with defaults.
+ *
+ * @packageDocumentation
+ */
+/**
+ * One field of a protobuf message, mirroring a `FieldDescriptorProto` at the
+ * field level. Matches the chain's `FieldShape` (camelCase, defaults for
+ * `repeated`/`optional`).
+ */
+export interface FieldShape {
+    name: string;
+    number: number;
+    typeName: string;
+    repeated: boolean;
+    optional: boolean;
+}
+/** A protobuf message projection. Matches the chain's `MessageShape`. */
+export interface MessageShape {
+    typeName: string;
+    fields: FieldShape[];
+}
+/**
+ * The typed, proto-faithful projection of a registered schema. Matches the
+ * chain's `MachineShape`: the state message plus one message per command/event,
+ * keyed by event name.
+ */
+export interface MachineShape {
+    stateMessage: MessageShape;
+    commands: Record<string, MessageShape>;
+}
+/**
+ * A JSON-Logic `StateMachineDefinition` as the chain decodes it. Kept as an
+ * opaque JSON object: the chain owns its meaning and its hashing. `from`/`to`
+ * and the `states` keys are bare strings (the chain's `StateId` encodes as a
+ * string); `dependencies` defaults to `[]` and state `metadata` to `null`.
+ */
+export interface StateMachineDefinition {
+    states: Record<string, {
+        id: string;
+        isFinal: boolean;
+        metadata: unknown | null;
+    }>;
+    initialState: string;
+    transitions: Array<{
+        from: string;
+        to: string;
+        eventName: string;
+        guard: unknown;
+        effect: unknown;
+        dependencies: unknown[];
+    }>;
+    metadata: unknown | null;
+}
+/**
+ * One package to pre-register at genesis. This is the genesis INPUT, not the
+ * chain's stored `RegisteredVersion`: it carries CONTENT only and the chain
+ * derives `schemaHash` / `logicHash` from it.
+ */
+export interface GenesisPackage {
+    /** RegistryName `"<labels>.package"`, e.g. `std.identity.package`. */
+    name: string;
+    /** SemVer of this initial version. */
+    semver: string;
+    /** Opt-in runtime conformance gate (`RegisteredVersion.strict`). */
+    strict: boolean;
+    /** Free-form notes map (<=8 entries, key <=32 chars, value <=128 chars). */
+    metadata: Record<string, string>;
+    /** Typed, proto-faithful projection of the app's schema. */
+    machineShape: MachineShape;
+    /** The JSON-Logic state-machine definition, verbatim. */
+    definition: StateMachineDefinition;
+}
+/** The full genesis manifest the chain consumes to bootstrap its registry. */
+export interface GenesisManifest {
+    version: number;
+    packages: GenesisPackage[];
+}
+/** Manifest schema version. Bump on any breaking change to the shape. */
+export declare const GENESIS_MANIFEST_VERSION = 1;
+/**
+ * Assemble the genesis manifest for the standard apps.
+ *
+ * Covers THREE apps in this first cut — identity, governance, markets (all the
+ * `universal` variant). The other std apps (contracts, oracles, corporate) and
+ * non-universal variants are a flagged follow-up.
+ *
+ * @returns a `GenesisManifest` whose JSON deserializes against the chain's circe
+ *   codecs. Hashes are intentionally absent — the chain derives them.
+ */
+export declare function buildGenesisManifest(): GenesisManifest;

package/dist/types/ottochain/index.d.ts

@@ -6,13 +6,14 @@
  * @packageDocumentation
  */
 export * as proto from '../generated/index.js';
-export type { Address, FiberId, StateId, HashValue, FiberOrdinal, SnapshotOrdinal, JsonLogicValue, JsonLogicExpression, FiberStatus, AccessControlPolicy, StateMachineDefinition, EmittedEvent, EventReceipt, OracleInvocation, FiberLogEntry, StateMachineFiberRecord, ScriptFiberRecord, FiberRecord, FiberCommit, OnChain, CalculatedState, CreateStateMachine, TransitionStateMachine, ArchiveStateMachine, CreateScript, InvokeScript, OttochainMessage, OttochainMessageType, } from './types.js';
-export { OTTOCHAIN_MESSAGE_TYPES } from './types.js';
+export type { Address, FiberId, StateId, HashValue, FiberOrdinal, SnapshotOrdinal, JsonLogicValue, JsonLogicExpression, FiberStatus, AccessControlPolicy, StateMachineDefinition, SemVer, RegistryStatus, VersionReq, SchemaRef, FieldShape, MessageShape, MachineShape, ScriptShape, RegistryShape, SchemaBinding, RegisteredVersion, VersionLineage, RegistryTarget, RegistryEntry, EmittedEvent, EventReceipt, ScriptInvocation, CreationReceipt, UpgradeReceipt, RejectionReceipt, FiberLogEntry, StateMachineFiberRecord, ScriptFiberRecord, FiberRecord, FiberCommit, OnChain, CalculatedState, CreateStateMachine, TransitionStateMachine, ArchiveStateMachine, UpgradeFiber, CreateScript, InvokeScript, UpgradeScript, PublishMachineVersion, PublishScriptVersion, SetVersionStatus, RegisterAlias, CreateAssetPolicy, MintAsset, ApplyMorphism, AuthorizeCompose, OttochainMessage, OttochainMessageType, MorphismKind, MorphismVisibility, TokenBehavior, SupplyPolicy, MorphismSpec, AssetHolder, OriginProvenance, ComponentWitness, AssetRecord, AssetCommit, } from './types.js';
+export { OTTOCHAIN_MESSAGE_TYPES, TOKEN_BEHAVIOR_BITS } from './types.js';
 export type { CurrencySnapshotResponse } from './snapshot.js';
 export { decodeOnChainState, getSnapshotOnChainState, getLatestOnChainState, getLogsForFiber, getEventReceipts, getScriptInvocations, extractOnChainState, } from './snapshot.js';
-export type { Checkpoint, MetagraphClientConfig, SubscribeOptions, FiberStateCallback, Unsubscribe, } from './metagraph-client.js';
+export type { Checkpoint, StateProof, FeeEstimate, MetagraphClientConfig, SubscribeOptions, FiberStateCallback, Unsubscribe, } from './metagraph-client.js';
 export { MetagraphClient } from './metagraph-client.js';
-export { createTransitionPayload, createArchivePayload, createInvokeScriptPayload, signTransaction, addTransactionSignature, getPublicKeyForRegistration, createStateMachinePayload, createScriptPayload, createDataTransactionRequest, } from './transaction.js';
+export { createTransitionPayload, createArchivePayload, createInvokeScriptPayload, signTransaction, addTransactionSignature, getPublicKeyForRegistration, createStateMachinePayload, createScriptPayload, createDataTransactionRequest, createAssetPolicyPayload, createMintAssetPayload, createApplyMorphismPayload, createAuthorizeComposePayload, } from './transaction.js';
 export type { CreateStateMachineParams, CreateStateMachineMessage, CreateScriptParams, CreateScriptMessage, DataTransactionRequest, TransitionParams, TransitionStateMachineMessage, ArchiveParams, ArchiveStateMachineMessage, InvokeScriptParams, InvokeScriptMessage, } from './transaction.js';
-export { normalizeCreateStateMachine, normalizeTransitionStateMachine, normalizeArchiveStateMachine, normalizeMessage, } from './normalize.js';
 export { dropNulls } from './drop-nulls.js';
+export { buildGenesisManifest, GENESIS_MANIFEST_VERSION } from './genesis-manifest.js';
+export type { GenesisManifest, GenesisPackage, MachineShape as GenesisMachineShape, MessageShape as GenesisMessageShape, FieldShape as GenesisFieldShape, StateMachineDefinition as GenesisStateMachineDefinition, } from './genesis-manifest.js';

package/dist/types/ottochain/metagraph-client.d.ts

@@ -4,12 +4,12 @@
  * Client for interacting with ottochain ML0 custom routes (/v1 prefix)
  * and framework snapshot endpoints.
  *
- * @see modules/l0/src/main/scala/xyz/kd5ujc/metagraph_l0/ML0CustomRoutes.scala
+ * @see modules/l0/src/main/scala/xyz/kd5ujc/metagraph_l0/ML0Routes.scala
  * @see modules/data_l1/src/main/scala/xyz/kd5ujc/data_l1/DataL1CustomRoutes.scala
  * @packageDocumentation
  */
 import type { Signed } from '@constellation-network/metagraph-sdk';
-import type { OnChain, CalculatedState, StateMachineFiberRecord, ScriptFiberRecord, EventReceipt, OracleInvocation, FiberStatus } from './types.js';
+import type { OnChain, CalculatedState, StateMachineFiberRecord, ScriptFiberRecord, EventReceipt, ScriptInvocation, FiberStatus, RegistryEntry } from './types.js';
 /**
  * Checkpoint response from the metagraph (ordinal + calculated state).
  */
@@ -17,6 +17,28 @@ export interface Checkpoint {
     ordinal: number;
     state: CalculatedState;
 }
+/**
+ * A light-client state proof for one field of a fiber/asset record, verifiable against the
+ * consensus-signed committed-state root (Merkle-Patricia inclusion). Returned by the `state-proof`
+ * endpoints.
+ */
+export interface StateProof {
+    /** The record (or projected field) the proof attests to. */
+    record: unknown;
+    /** The committed-state combined root (= the snapshot's `calculatedStateProof`). */
+    committedRoot: string;
+    /** The Merkle-Patricia trie root. */
+    mptRoot: string;
+    ordinal: number;
+    /** The Merkle-Patricia inclusion proof. */
+    proof: unknown;
+}
+/** A fee/gas estimate for a transition or script invocation (shape is advisory / may evolve). */
+export interface FeeEstimate {
+    gas?: number;
+    fee?: number;
+    [key: string]: unknown;
+}
 /**
  * Options for subscribeFiberState polling behaviour.
  */
@@ -86,7 +108,7 @@ export interface MetagraphClientConfig {
  * const onChain = await client.getOnChain();
  *
  * // Get all active state machines
- * const machines = await client.getStateMachines('Active');
+ * const machines = await client.getStateMachines('ACTIVE');
  *
  * // Get event receipts for a fiber
  * const events = await client.getStateMachineEvents(fiberId);
@@ -118,17 +140,37 @@ export declare class MetagraphClient {
      */
     getStateMachineEvents(fiberId: string): Promise<EventReceipt[]>;
     /**
-     * Get all script oracles, optionally filtered by status.
+     * Get all scripts, optionally filtered by status.
      */
     getScripts(status?: FiberStatus): Promise<Record<string, ScriptFiberRecord>>;
     /**
-     * Get a single script oracle by fiber ID.
+     * Get a single script by fiber ID.
      */
     getScript(scriptId: string): Promise<ScriptFiberRecord | null>;
     /**
-     * Get oracle invocations from the current ordinal's logs.
+     * Get script invocations from the current ordinal's logs.
      */
-    getScriptInvocations(scriptId: string): Promise<OracleInvocation[]>;
+    getScriptInvocations(scriptId: string): Promise<ScriptInvocation[]>;
+    /** Get the metagraph version string. */
+    getVersion(): Promise<string>;
+    /** Get the full registry namespace, keyed by full registry name `labels.tld`. */
+    getRegistry(): Promise<Record<string, RegistryEntry>>;
+    /** Resolve a single registry entry by full name (`labels.tld`), or null if unregistered. */
+    getRegistryEntry(name: string): Promise<RegistryEntry | null>;
+    /** Reverse-resolve a fiber UUID to its canonical registered name (#29), or null. */
+    getReverseName(fiberId: string): Promise<string | null>;
+    /** Get the rendered audit-trail lines for a state-machine fiber. */
+    getStateMachineAudit(fiberId: string): Promise<string[]>;
+    /** Light-client state proof for a field of a state-machine fiber, against the committed root. */
+    getStateMachineStateProof(fiberId: string, field: string): Promise<StateProof>;
+    /** Light-client state proof for a field of a script fiber. */
+    getScriptStateProof(fiberId: string, field: string): Promise<StateProof>;
+    /** Light-client state proof for a field of an asset instance. */
+    getAssetStateProof(assetId: string, field: string): Promise<StateProof>;
+    /** Estimate the fee/gas for a transition event on a state-machine fiber. */
+    estimateTransitionFee(fiberId: string, eventName: string): Promise<FeeEstimate>;
+    /** Estimate the fee/gas for invoking a script fiber. */
+    estimateScriptFee(fiberId: string): Promise<FeeEstimate>;
     /**
      * Get the latest snapshot and decode its on-chain state.
      */

package/dist/types/ottochain/snapshot.d.ts

@@ -9,7 +9,7 @@
  * @see modules/models/src/main/scala/xyz/kd5ujc/schema/OnChain.scala
  * @packageDocumentation
  */
-import type { OnChain, EventReceipt, OracleInvocation, FiberLogEntry } from './types.js';
+import type { OnChain, EventReceipt, ScriptInvocation, FiberLogEntry } from './types.js';
 /**
  * Decode on-chain state from binary (JsonBinaryCodec format).
  *
@@ -65,7 +65,7 @@ export declare function getLogsForFiber(onChain: OnChain, fiberId: string): Fibe
 /**
  * Get EventReceipt log entries for a specific fiber.
  *
- * EventReceipts are distinguished from OracleInvocations by the presence
+ * EventReceipts are distinguished from ScriptInvocations by the presence
  * of the `eventName` field.
  *
  * @param onChain - Decoded on-chain state
@@ -74,13 +74,13 @@ export declare function getLogsForFiber(onChain: OnChain, fiberId: string): Fibe
  */
 export declare function getEventReceipts(onChain: OnChain, fiberId: string): EventReceipt[];
 /**
- * Get OracleInvocation log entries for a specific fiber.
+ * Get ScriptInvocation log entries for a specific fiber.
  *
- * OracleInvocations are distinguished from EventReceipts by the presence
+ * ScriptInvocations are distinguished from EventReceipts by the presence
  * of the `method` field.
  *
  * @param onChain - Decoded on-chain state
  * @param fiberId - Fiber UUID to filter by
- * @returns Array of OracleInvocation entries
+ * @returns Array of ScriptInvocation entries
  */
-export declare function getScriptInvocations(onChain: OnChain, fiberId: string): OracleInvocation[];
+export declare function getScriptInvocations(onChain: OnChain, fiberId: string): ScriptInvocation[];

package/dist/types/ottochain/transaction.d.ts

@@ -5,6 +5,7 @@
  * self-signed mode, where clients sign their own transactions.
  */
 import type { Signed } from '@constellation-network/metagraph-sdk';
+import type { CreateAssetPolicy, MintAsset, ApplyMorphism, AuthorizeCompose } from './types.js';
 /**
  * Parameters for creating a new state machine fiber
  */
@@ -28,6 +29,13 @@ export interface CreateStateMachineMessage {
 /**
  * Create a new state machine fiber payload.
  *
+ * @remarks
+ * `params.definition` is signed VERBATIM. Pass the output of `toProtoDefinition(def)` (the
+ * allowlisted wire shape) — NOT a raw `FiberAppDefinition`: extra authoring fields
+ * (`createSchema` / `stateSchema` / `eventSchemas` / per-transition `emits`) would be signed
+ * but re-encoded away by the chain, diverging the canonical → opaque `InvalidSignature`.
+ * See `tests/ottochain/signing-parity.test.ts`.
+ *
  * @param params - State machine creation parameters
  * @returns A CreateStateMachine message ready for signing
  *
@@ -145,7 +153,7 @@ export interface CreateScriptMessage {
  *     },
  *   },
  *   initialState: { value: 0 },
- *   accessControl: { type: 'open' },
+ *   accessControl: { Public: {} },
  * });
  * const signed = await signTransaction(script, privateKey);
  * ```
@@ -178,12 +186,33 @@ export interface InvokeScriptMessage {
  * @returns An InvokeScript message ready for signing
  */
 export declare function createInvokeScriptPayload(params: InvokeScriptParams): InvokeScriptMessage;
+/** Wrap a {@link CreateAssetPolicy} (publish an asset-policy package version). */
+export declare function createAssetPolicyPayload(params: CreateAssetPolicy): {
+    CreateAssetPolicy: CreateAssetPolicy;
+};
+/** Wrap a {@link MintAsset} (mint a new asset instance against a resolved policy version). */
+export declare function createMintAssetPayload(params: MintAsset): {
+    MintAsset: MintAsset;
+};
+/** Wrap an {@link ApplyMorphism} (apply a typed morphism to an asset instance). */
+export declare function createApplyMorphismPayload(params: ApplyMorphism): {
+    ApplyMorphism: ApplyMorphism;
+};
+/** Wrap an {@link AuthorizeCompose} (commit half of the symmetric-compose handshake). */
+export declare function createAuthorizeComposePayload(params: AuthorizeCompose): {
+    AuthorizeCompose: AuthorizeCompose;
+};
 /**
  * Sign a transaction payload for self-signed mode.
  *
  * This creates a Signed<T> object with the exact format expected by the bridge's
  * `/agent/transition` endpoint when using self-signed mode.
  *
+ * The signature is computed over the null-dropped canonical bytes (null
+ * object fields removed recursively, array nulls preserved, then RFC 8785),
+ * matching metakit's content-hash rule. Explicit-null and absent optional
+ * fields therefore produce identical signatures.
+ *
  * @param message - The message to sign (e.g., from createTransitionPayload)
  * @param privateKey - The private key in hex format (64 characters)
  * @returns A signed object ready for submission to the bridge
@@ -251,6 +280,9 @@ export declare function createDataTransactionRequest<T>(signed: Signed<T>): Data
  * Use this for multi-signature scenarios where multiple parties
  * need to sign the same transaction.
  *
+ * The new signature is computed over the null-dropped canonical bytes,
+ * matching metakit's content-hash rule (see {@link signTransaction}).
+ *
  * @param signed - The already-signed transaction
  * @param privateKey - Additional signer's private key
  * @returns Transaction with additional signature