@ottochain/sdk 1.1.1 → 1.3.0

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

@@ -11,3 +11,7 @@ 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 { MetagraphClient } from './metagraph-client.js';
+export { createTransitionPayload, createArchivePayload, createInvokeScriptPayload, signTransaction, addTransactionSignature, getPublicKeyForRegistration, createStateMachinePayload, createScriptPayload, createDataTransactionRequest, } 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';

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

@@ -8,6 +8,7 @@
  * @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';
 /**
  * Checkpoint response from the metagraph (ordinal + calculated state).
@@ -63,6 +64,8 @@ export interface MetagraphClientConfig {
     ml0Url: string;
     /** DL1 node base URL for data submission (e.g., 'http://localhost:9400') */
     dl1Url?: string;
+    /** Multiple DL1 node URLs for resilient data submission */
+    dl1Urls?: string[];
     /** Request timeout in milliseconds (default: 30000) */
     timeout?: number;
 }
@@ -92,6 +95,7 @@ export interface MetagraphClientConfig {
 export declare class MetagraphClient {
     private ml0;
     private dl1?;
+    private dl1Clients;
     constructor(config: MetagraphClientConfig);
     /**
      * Get the current on-chain state (directly from L0 context).
@@ -198,4 +202,28 @@ export declare class MetagraphClient {
     postData<T>(signedData: T): Promise<{
         hash: string;
     }>;
+    /**
+     * Submit a self-signed transaction directly to DL1 nodes.
+     *
+     * Wraps the signed payload in `{ data, fee: null }` format and submits
+     * to one of the configured DL1 nodes. Uses `Promise.any` when multiple
+     * DL1 URLs are configured for resilience.
+     *
+     * @param signed - A `Signed<T>` object from `signTransaction()`
+     * @returns Response containing the data hash
+     * @throws Error if no DL1 URLs are configured or all nodes fail
+     *
+     * @example
+     * ```typescript
+     * const metagraph = new MetagraphClient({
+     *   ml0Url: 'http://localhost:9200',
+     *   dl1Urls: ['http://node1:9400', 'http://node2:9400'],
+     * });
+     * const signed = await signTransaction(payload, privateKey);
+     * await metagraph.submitData(signed);
+     * ```
+     */
+    submitData<T>(signed: Signed<T>): Promise<{
+        hash: string;
+    }>;
 }

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

@@ -0,0 +1,283 @@
+/**
+ * Transaction Helpers for Self-Signed Mode
+ *
+ * These helpers create properly formatted payloads for the bridge's
+ * self-signed mode, where clients sign their own transactions.
+ */
+import type { Signed } from '@constellation-network/metagraph-sdk';
+/**
+ * Parameters for creating a new state machine fiber
+ */
+export interface CreateStateMachineParams {
+    fiberId: string;
+    definition: Record<string, unknown>;
+    initialData?: Record<string, unknown>;
+    parentFiberId?: string;
+}
+/**
+ * A CreateStateMachine message ready for signing
+ */
+export interface CreateStateMachineMessage {
+    CreateStateMachine: {
+        fiberId: string;
+        definition: Record<string, unknown>;
+        initialData: Record<string, unknown>;
+        parentFiberId?: string;
+    };
+}
+/**
+ * Create a new state machine fiber payload.
+ *
+ * @param params - State machine creation parameters
+ * @returns A CreateStateMachine message ready for signing
+ *
+ * @example
+ * ```typescript
+ * const create = createStateMachinePayload({
+ *   fiberId: crypto.randomUUID(),
+ *   definition: {
+ *     states: { CREATED: { on: { activate: 'ACTIVE' } }, ACTIVE: {} },
+ *     initialState: 'CREATED',
+ *   },
+ *   initialData: { owner: myAddress },
+ * });
+ * const signed = await signTransaction(create, privateKey);
+ * ```
+ */
+export declare function createStateMachinePayload(params: CreateStateMachineParams): CreateStateMachineMessage;
+/**
+ * Parameters for creating a transition payload
+ */
+export interface TransitionParams {
+    fiberId: string;
+    eventName: string;
+    payload?: Record<string, unknown>;
+    targetSequenceNumber: number;
+}
+/**
+ * A TransitionStateMachine message ready for signing
+ */
+export interface TransitionStateMachineMessage {
+    TransitionStateMachine: {
+        fiberId: string;
+        eventName: string;
+        payload: Record<string, unknown>;
+        targetSequenceNumber: number;
+    };
+}
+/**
+ * Create a transition payload ready for signing.
+ *
+ * This creates the exact message structure expected by the metagraph.
+ *
+ * @param params - Transition parameters
+ * @returns A TransitionStateMachine message ready for signing
+ *
+ * @example
+ * ```typescript
+ * const transition = createTransitionPayload({
+ *   fiberId: 'my-fiber-id',
+ *   eventName: 'activate',
+ *   payload: {},
+ *   targetSequenceNumber: 0,
+ * });
+ * ```
+ */
+export declare function createTransitionPayload(params: TransitionParams): TransitionStateMachineMessage;
+/**
+ * Parameters for creating an archive payload
+ */
+export interface ArchiveParams {
+    fiberId: string;
+    targetSequenceNumber: number;
+}
+/**
+ * An ArchiveStateMachine message ready for signing
+ */
+export interface ArchiveStateMachineMessage {
+    ArchiveStateMachine: {
+        fiberId: string;
+        targetSequenceNumber: number;
+    };
+}
+/**
+ * Create an archive payload ready for signing.
+ *
+ * @param params - Archive parameters
+ * @returns An ArchiveStateMachine message ready for signing
+ */
+export declare function createArchivePayload(params: ArchiveParams): ArchiveStateMachineMessage;
+/**
+ * Parameters for creating a new script fiber
+ */
+export interface CreateScriptParams {
+    fiberId: string;
+    scriptProgram: Record<string, unknown>;
+    initialState?: Record<string, unknown> | unknown[];
+    accessControl?: Record<string, unknown>;
+}
+/**
+ * A CreateScript message ready for signing
+ */
+export interface CreateScriptMessage {
+    CreateScript: {
+        fiberId: string;
+        scriptProgram: Record<string, unknown>;
+        initialState: Record<string, unknown> | unknown[] | null;
+        accessControl: Record<string, unknown>;
+    };
+}
+/**
+ * Create a new script fiber payload.
+ *
+ * Note: `initialState` must be an object or array, NOT a primitive.
+ *
+ * @param params - Script creation parameters
+ * @returns A CreateScript message ready for signing
+ *
+ * @example
+ * ```typescript
+ * const script = createScriptPayload({
+ *   fiberId: crypto.randomUUID(),
+ *   scriptProgram: {
+ *     methods: {
+ *       increment: { "+": [{ var: "state.value" }, 1] },
+ *     },
+ *   },
+ *   initialState: { value: 0 },
+ *   accessControl: { type: 'open' },
+ * });
+ * const signed = await signTransaction(script, privateKey);
+ * ```
+ */
+export declare function createScriptPayload(params: CreateScriptParams): CreateScriptMessage;
+/**
+ * Parameters for creating an invoke script payload
+ */
+export interface InvokeScriptParams {
+    fiberId: string;
+    method: string;
+    args?: Record<string, unknown>;
+    targetSequenceNumber: number;
+}
+/**
+ * An InvokeScript message ready for signing
+ */
+export interface InvokeScriptMessage {
+    InvokeScript: {
+        fiberId: string;
+        method: string;
+        args: Record<string, unknown>;
+        targetSequenceNumber: number;
+    };
+}
+/**
+ * Create an invoke script payload ready for signing.
+ *
+ * @param params - Invoke script parameters
+ * @returns An InvokeScript message ready for signing
+ */
+export declare function createInvokeScriptPayload(params: InvokeScriptParams): InvokeScriptMessage;
+/**
+ * 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.
+ *
+ * @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
+ *
+ * @example
+ * ```typescript
+ * import { createTransitionPayload, signTransaction, generateKeyPair } from '@ottochain/sdk';
+ *
+ * const keyPair = generateKeyPair();
+ *
+ * // Create the transition message
+ * const transition = createTransitionPayload({
+ *   fiberId: 'my-fiber-id',
+ *   eventName: 'activate',
+ *   payload: {},
+ *   targetSequenceNumber: 0,
+ * });
+ *
+ * // Sign it
+ * const signedUpdate = await signTransaction(transition, keyPair.privateKey);
+ *
+ * // Submit to bridge
+ * await fetch('https://bridge/agent/transition', {
+ *   method: 'POST',
+ *   body: JSON.stringify({
+ *     fiberId: 'my-fiber-id',
+ *     signedUpdate,
+ *   }),
+ * });
+ * ```
+ */
+export declare function signTransaction<T>(message: T, privateKey: string): Promise<Signed<T>>;
+/**
+ * A DataTransactionRequest ready for submission to the DL1 `/data` endpoint.
+ */
+export interface DataTransactionRequest<T> {
+    data: Signed<T>;
+    fee: null;
+}
+/**
+ * Wrap a signed transaction in the DataTransactionRequest format
+ * expected by tessellation's DL1 `/data` endpoint.
+ *
+ * @param signed - A signed transaction from signTransaction()
+ * @returns Payload ready for POST to DL1 `/data`
+ *
+ * @example
+ * ```typescript
+ * const transition = createTransitionPayload({ ... });
+ * const signed = await signTransaction(transition, privateKey);
+ * const payload = createDataTransactionRequest(signed);
+ *
+ * // Submit directly to DL1
+ * await fetch('http://dl1-node:9400/data', {
+ *   method: 'POST',
+ *   headers: { 'Content-Type': 'application/json' },
+ *   body: JSON.stringify(payload),
+ * });
+ * ```
+ */
+export declare function createDataTransactionRequest<T>(signed: Signed<T>): DataTransactionRequest<T>;
+/**
+ * Add an additional signature to a signed transaction.
+ *
+ * Use this for multi-signature scenarios where multiple parties
+ * need to sign the same transaction.
+ *
+ * @param signed - The already-signed transaction
+ * @param privateKey - Additional signer's private key
+ * @returns Transaction with additional signature
+ */
+export declare function addTransactionSignature<T>(signed: Signed<T>, privateKey: string): Promise<Signed<T>>;
+/**
+ * Get the public key ID from a private key in the format expected by registration.
+ *
+ * The bridge's self-signed registration expects the public key as a 128-character
+ * hex string (without the 04 prefix).
+ *
+ * @param privateKey - Private key in hex format
+ * @returns Public key ID (128 chars, no prefix)
+ *
+ * @example
+ * ```typescript
+ * const keyPair = generateKeyPair();
+ * const publicKeyId = getPublicKeyForRegistration(keyPair.privateKey);
+ *
+ * await fetch('https://bridge/agent/register', {
+ *   method: 'POST',
+ *   body: JSON.stringify({
+ *     signingMode: 'self',
+ *     publicKey: publicKeyId,
+ *     displayName: 'My Agent',
+ *   }),
+ * });
+ * ```
+ */
+export declare function getPublicKeyForRegistration(privateKey: string): string;

package/dist/types/validation.d.ts

@@ -142,11 +142,11 @@ export declare const TransactionReferenceSchema: z.ZodObject<{
     ordinal: z.ZodNumber;
     hash: z.ZodString;
 }, "strip", z.ZodTypeAny, {
-    hash: string;
     ordinal: number;
-}, {
     hash: string;
+}, {
     ordinal: number;
+    hash: string;
 }>;
 /**
  * Schema for CurrencyTransactionValue
@@ -191,11 +191,11 @@ export declare const CurrencyTransactionSchema: z.ZodObject<{
         ordinal: z.ZodNumber;
         hash: z.ZodString;
     }, "strip", z.ZodTypeAny, {
-        hash: string;
         ordinal: number;
-    }, {
         hash: string;
+    }, {
         ordinal: number;
+        hash: string;
     }>;
 }, "strip", z.ZodTypeAny, {
     value: {
@@ -205,8 +205,8 @@ export declare const CurrencyTransactionSchema: z.ZodObject<{
         fee: number;
     };
     parent: {
-        hash: string;
         ordinal: number;
+        hash: string;
     };
 }, {
     value: {
@@ -216,8 +216,8 @@ export declare const CurrencyTransactionSchema: z.ZodObject<{
         fee?: number | undefined;
     };
     parent: {
-        hash: string;
         ordinal: number;
+        hash: string;
     };
 }>;
 /**
@@ -233,14 +233,14 @@ export declare const TransferParamsSchema: z.ZodObject<{
     amount: z.ZodNumber;
     fee: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
 }, "strip", z.ZodTypeAny, {
-    amount: number;
     from: string;
     to: string;
+    amount: number;
     fee: number;
 }, {
-    amount: number;
     from: string;
     to: string;
+    amount: number;
     fee?: number | undefined;
 }>;
 /**

package/dist/types/verify.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Backward-compatible verify wrapper.
+ *
+ * The package embeds `mode: "standard"|"dataUpdate"` in signed objects and
+ * its verify() ignores the `isDataUpdate` parameter when `mode` is present.
+ * This wrapper strips `mode` so callers' explicit `isDataUpdate` always wins.
+ */
+import type { Signed, VerificationResult } from '@constellation-network/metagraph-sdk';
+export declare function verify<T>(signed: Signed<T>, isDataUpdate?: boolean): VerificationResult;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ottochain/sdk",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "description": "TypeScript SDK for ottochain metagraph operations - signing, encoding, and network interactions",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -104,6 +104,7 @@
   },
   "dependencies": {
     "@bufbuild/protobuf": "^2.11.0",
+    "@constellation-network/metagraph-sdk": "^0.2.0",
     "@stardust-collective/dag4": "^2.6.0",
     "@stardust-collective/dag4-keystore": "^2.6.0",
     "canonicalize": "^2.1.0",
@@ -112,8 +113,9 @@
     "zod": "^3.22.0"
   },
   "devDependencies": {
+    "@babel/preset-env": "^7.29.0",
     "@types/jest": "^30.0.0",
-    "@types/node": "^20.0.0",
+    "@types/node": "^25.3.3",
     "@typescript-eslint/eslint-plugin": "^8.56.1",
     "@typescript-eslint/parser": "^8.56.1",
     "eslint": "^9.39.3",
@@ -128,7 +130,7 @@
     "@stardust-collective/dag4": "^2.6.0"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.19.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org"

package/dist/cjs/metakit/binary.js

@@ -1,58 +0,0 @@
-"use strict";
-/**
- * Binary Encoding
- *
- * Converts JSON data to binary format for cryptographic operations.
- * Supports both regular encoding and DataUpdate encoding with Constellation prefix.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.encodeDataUpdate = exports.toBytes = void 0;
-const canonicalize_js_1 = require("./canonicalize.js");
-const types_js_1 = require("./types.js");
-/**
- * Convert data to binary bytes for signing
- *
- * For regular data:
- *   JSON -> RFC 8785 canonicalization -> UTF-8 bytes
- *
- * For DataUpdate (isDataUpdate=true):
- *   JSON -> RFC 8785 -> UTF-8 -> Base64 -> prepend Constellation prefix -> UTF-8 bytes
- *
- * @param data - Any JSON-serializable object
- * @param isDataUpdate - If true, applies DataUpdate encoding with Constellation prefix
- * @returns Binary bytes as Uint8Array
- *
- * @example
- * ```typescript
- * // Regular encoding
- * const bytes = toBytes({ action: 'test' });
- *
- * // DataUpdate encoding
- * const updateBytes = toBytes({ action: 'test' }, true);
- * ```
- */
-function toBytes(data, isDataUpdate = false) {
-    const canonicalJson = (0, canonicalize_js_1.canonicalize)(data);
-    const utf8Bytes = new TextEncoder().encode(canonicalJson);
-    if (isDataUpdate) {
-        // Base64 encode the UTF-8 bytes
-        const base64String = Buffer.from(utf8Bytes).toString('base64');
-        // Create the wrapped string with Constellation prefix
-        const wrappedString = `${types_js_1.CONSTELLATION_PREFIX}${base64String.length}\n${base64String}`;
-        return new TextEncoder().encode(wrappedString);
-    }
-    return utf8Bytes;
-}
-exports.toBytes = toBytes;
-/**
- * Encode data as a DataUpdate with Constellation prefix
- *
- * This is equivalent to `toBytes(data, true)`.
- *
- * @param data - Any JSON-serializable object
- * @returns Binary bytes with Constellation prefix
- */
-function encodeDataUpdate(data) {
-    return toBytes(data, true);
-}
-exports.encodeDataUpdate = encodeDataUpdate;

package/dist/cjs/metakit/canonicalize.js

@@ -1,40 +0,0 @@
-"use strict";
-/**
- * RFC 8785 JSON Canonicalization
- *
- * Provides deterministic JSON serialization according to RFC 8785.
- * This ensures identical JSON objects always produce identical strings.
- */
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.canonicalize = void 0;
-const canonicalize_1 = __importDefault(require("canonicalize"));
-/**
- * Canonicalize JSON data according to RFC 8785
- *
- * Key features:
- * - Object keys sorted by UTF-16BE binary comparison
- * - Numbers serialized in shortest decimal representation
- * - No whitespace
- * - Proper Unicode escaping
- *
- * @param data - Any JSON-serializable object
- * @returns Canonical JSON string
- * @throws Error if data cannot be serialized to JSON
- *
- * @example
- * ```typescript
- * const canonical = canonicalize({ b: 2, a: 1 });
- * // Returns: '{"a":1,"b":2}'
- * ```
- */
-function canonicalize(data) {
-    const result = (0, canonicalize_1.default)(data);
-    if (result === undefined) {
-        throw new Error('Failed to canonicalize data: data cannot be serialized to JSON');
-    }
-    return result;
-}
-exports.canonicalize = canonicalize;

package/dist/cjs/metakit/codec.js

@@ -1,45 +0,0 @@
-"use strict";
-/**
- * Codec Utilities
- *
- * Encoding/decoding utilities for the Constellation signature protocol.
- * Re-exports from binary.ts for backwards compatibility and provides additional utilities.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.decodeDataUpdate = exports.CONSTELLATION_PREFIX = exports.encodeDataUpdate = exports.toBytes = void 0;
-var binary_js_1 = require("./binary.js");
-Object.defineProperty(exports, "toBytes", { enumerable: true, get: function () { return binary_js_1.toBytes; } });
-Object.defineProperty(exports, "encodeDataUpdate", { enumerable: true, get: function () { return binary_js_1.encodeDataUpdate; } });
-var types_js_1 = require("./types.js");
-Object.defineProperty(exports, "CONSTELLATION_PREFIX", { enumerable: true, get: function () { return types_js_1.CONSTELLATION_PREFIX; } });
-/**
- * Decode a DataUpdate encoded message back to its original JSON
- *
- * @param bytes - DataUpdate encoded bytes
- * @returns Decoded JSON object
- * @throws Error if bytes are not valid DataUpdate encoding
- */
-function decodeDataUpdate(bytes) {
-    const text = new TextDecoder().decode(bytes);
-    // Validate prefix
-    if (!text.startsWith('\x19Constellation Signed Data:\n')) {
-        throw new Error('Invalid DataUpdate encoding: missing Constellation prefix');
-    }
-    // Parse the format: \x19Constellation Signed Data:\n{length}\n{base64}
-    const withoutPrefix = text.slice('\x19Constellation Signed Data:\n'.length);
-    const newlineIndex = withoutPrefix.indexOf('\n');
-    if (newlineIndex === -1) {
-        throw new Error('Invalid DataUpdate encoding: missing length delimiter');
-    }
-    const lengthStr = withoutPrefix.slice(0, newlineIndex);
-    const base64Data = withoutPrefix.slice(newlineIndex + 1);
-    const expectedLength = parseInt(lengthStr, 10);
-    if (isNaN(expectedLength) || base64Data.length !== expectedLength) {
-        throw new Error('Invalid DataUpdate encoding: length mismatch');
-    }
-    // Decode base64 to UTF-8 JSON
-    const jsonBytes = Buffer.from(base64Data, 'base64');
-    const jsonString = new TextDecoder().decode(jsonBytes);
-    return JSON.parse(jsonString);
-}
-exports.decodeDataUpdate = decodeDataUpdate;