@ottochain/sdk 1.1.1 → 1.2.0

package/dist/cjs/index.js

@@ -29,7 +29,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.assert = exports.safeParse = exports.validateKeyPair = exports.validateAddress = exports.validatePublicKey = exports.validatePrivateKey = exports.validate = exports.CompleteContractRequestSchema = exports.AcceptContractRequestSchema = exports.ProposeContractRequestSchema = exports.ContractTermsSchema = exports.PlatformLinkSchema = exports.AgentIdentityRegistrationSchema = exports.TransferParamsSchema = exports.CurrencyTransactionSchema = exports.CurrencyTransactionValueSchema = exports.TransactionReferenceSchema = exports.SignedSchema = exports.SignatureProofSchema = exports.KeyPairSchema = exports.PublicKeySchema = exports.PrivateKeySchema = exports.DagAddressSchema = exports.wrapError = exports.isErrorCode = exports.ErrorCode = exports.TransactionError = exports.SigningError = exports.ValidationError = exports.NetworkError = exports.OttoChainError = void 0;
+exports.MetagraphClient = exports.assert = exports.safeParse = exports.validateKeyPair = exports.validateAddress = exports.validatePublicKey = exports.validatePrivateKey = exports.validate = exports.CompleteContractRequestSchema = exports.AcceptContractRequestSchema = exports.ProposeContractRequestSchema = exports.ContractTermsSchema = exports.PlatformLinkSchema = exports.AgentIdentityRegistrationSchema = exports.TransferParamsSchema = exports.CurrencyTransactionSchema = exports.CurrencyTransactionValueSchema = exports.TransactionReferenceSchema = exports.SignedSchema = exports.SignatureProofSchema = exports.KeyPairSchema = exports.PublicKeySchema = exports.PrivateKeySchema = exports.DagAddressSchema = exports.wrapError = exports.isErrorCode = exports.ErrorCode = exports.TransactionError = exports.SigningError = exports.ValidationError = exports.NetworkError = exports.OttoChainError = void 0;
 // Type aliases for semantic clarity (matches wire format)
 __exportStar(require("./types.js"), exports);
 // Metakit utilities (signing, hashing, HTTP client)
@@ -77,3 +77,6 @@ Object.defineProperty(exports, "assert", { enumerable: true, get: function () {
 __exportStar(require("./errors.js"), exports);
 // Validation schemas and helpers
 __exportStar(require("./validation.js"), exports);
+// Ottochain metagraph client
+var metagraph_client_js_1 = require("./ottochain/metagraph-client.js");
+Object.defineProperty(exports, "MetagraphClient", { enumerable: true, get: function () { return metagraph_client_js_1.MetagraphClient; } });

package/dist/cjs/metakit/index.js

@@ -8,7 +8,7 @@
  * @packageDocumentation
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NetworkError = exports.HttpClient = exports.DataL1Client = exports.CurrencyL1Client = exports.unitsToToken = exports.tokenToUnits = exports.isValidDagAddress = exports.getTransactionReference = exports.hashCurrencyTransaction = exports.encodeCurrencyTransaction = exports.verifyCurrencyTransaction = exports.signCurrencyTransaction = exports.createCurrencyTransactionBatch = exports.createCurrencyTransaction = exports.TOKEN_DECIMALS = exports.isValidPublicKey = exports.isValidPrivateKey = exports.getAddress = exports.getPublicKeyId = exports.getPublicKeyHex = exports.keyPairFromPrivateKey = exports.generateKeyPair = exports.batchSign = exports.addSignature = exports.createSignedObject = exports.verifySignature = exports.verifyHash = exports.verify = exports.signHash = exports.signDataUpdate = exports.sign = exports.decodeDataUpdate = exports.computeDigest = exports.hashData = exports.hashBytes = exports.hash = exports.encodeDataUpdate = exports.toBytes = exports.canonicalize = exports.CONSTELLATION_PREFIX = exports.ALGORITHM = void 0;
+exports.createDataTransactionRequest = exports.createScriptPayload = exports.createStateMachinePayload = exports.getPublicKeyForRegistration = exports.addTransactionSignature = exports.signTransaction = exports.createInvokeScriptPayload = exports.createArchivePayload = exports.createTransitionPayload = exports.NetworkError = exports.HttpClient = exports.DataL1Client = exports.CurrencyL1Client = exports.unitsToToken = exports.tokenToUnits = exports.isValidDagAddress = exports.getTransactionReference = exports.hashCurrencyTransaction = exports.encodeCurrencyTransaction = exports.verifyCurrencyTransaction = exports.signCurrencyTransaction = exports.createCurrencyTransactionBatch = exports.createCurrencyTransaction = exports.TOKEN_DECIMALS = exports.isValidPublicKey = exports.isValidPrivateKey = exports.getAddress = exports.getPublicKeyId = exports.getPublicKeyHex = exports.keyPairFromPrivateKey = exports.generateKeyPair = exports.batchSign = exports.addSignature = exports.createSignedObject = exports.verifySignature = exports.verifyHash = exports.verify = exports.signHash = exports.signDataUpdate = exports.sign = exports.decodeDataUpdate = exports.computeDigest = exports.hashData = exports.hashBytes = exports.hash = exports.encodeDataUpdate = exports.toBytes = exports.canonicalize = exports.CONSTELLATION_PREFIX = exports.ALGORITHM = void 0;
 var types_js_1 = require("./types.js");
 Object.defineProperty(exports, "ALGORITHM", { enumerable: true, get: function () { return types_js_1.ALGORITHM; } });
 Object.defineProperty(exports, "CONSTELLATION_PREFIX", { enumerable: true, get: function () { return types_js_1.CONSTELLATION_PREFIX; } });
@@ -72,3 +72,15 @@ Object.defineProperty(exports, "CurrencyL1Client", { enumerable: true, get: func
 Object.defineProperty(exports, "DataL1Client", { enumerable: true, get: function () { return index_js_1.DataL1Client; } });
 Object.defineProperty(exports, "HttpClient", { enumerable: true, get: function () { return index_js_1.HttpClient; } });
 Object.defineProperty(exports, "NetworkError", { enumerable: true, get: function () { return index_js_1.NetworkError; } });
+// Transaction helpers for self-signed mode
+var transaction_js_1 = require("./transaction.js");
+Object.defineProperty(exports, "createTransitionPayload", { enumerable: true, get: function () { return transaction_js_1.createTransitionPayload; } });
+Object.defineProperty(exports, "createArchivePayload", { enumerable: true, get: function () { return transaction_js_1.createArchivePayload; } });
+Object.defineProperty(exports, "createInvokeScriptPayload", { enumerable: true, get: function () { return transaction_js_1.createInvokeScriptPayload; } });
+Object.defineProperty(exports, "signTransaction", { enumerable: true, get: function () { return transaction_js_1.signTransaction; } });
+Object.defineProperty(exports, "addTransactionSignature", { enumerable: true, get: function () { return transaction_js_1.addTransactionSignature; } });
+Object.defineProperty(exports, "getPublicKeyForRegistration", { enumerable: true, get: function () { return transaction_js_1.getPublicKeyForRegistration; } });
+var transaction_js_2 = require("./transaction.js");
+Object.defineProperty(exports, "createStateMachinePayload", { enumerable: true, get: function () { return transaction_js_2.createStateMachinePayload; } });
+Object.defineProperty(exports, "createScriptPayload", { enumerable: true, get: function () { return transaction_js_2.createScriptPayload; } });
+Object.defineProperty(exports, "createDataTransactionRequest", { enumerable: true, get: function () { return transaction_js_2.createDataTransactionRequest; } });

package/dist/cjs/metakit/transaction.js

@@ -0,0 +1,252 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPublicKeyForRegistration = exports.addTransactionSignature = exports.createDataTransactionRequest = exports.signTransaction = exports.createInvokeScriptPayload = exports.createScriptPayload = exports.createArchivePayload = exports.createTransitionPayload = exports.createStateMachinePayload = void 0;
+const sign_js_1 = require("./sign.js");
+const wallet_js_1 = require("./wallet.js");
+/**
+ * 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);
+ * ```
+ */
+function createStateMachinePayload(params) {
+    return {
+        CreateStateMachine: {
+            fiberId: params.fiberId,
+            definition: params.definition,
+            initialData: params.initialData ?? {},
+            ...(params.parentFiberId ? { parentFiberId: params.parentFiberId } : {}),
+        },
+    };
+}
+exports.createStateMachinePayload = createStateMachinePayload;
+/**
+ * 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,
+ * });
+ * ```
+ */
+function createTransitionPayload(params) {
+    return {
+        TransitionStateMachine: {
+            fiberId: params.fiberId,
+            eventName: params.eventName,
+            payload: params.payload ?? {},
+            targetSequenceNumber: params.targetSequenceNumber,
+        },
+    };
+}
+exports.createTransitionPayload = createTransitionPayload;
+/**
+ * Create an archive payload ready for signing.
+ *
+ * @param params - Archive parameters
+ * @returns An ArchiveStateMachine message ready for signing
+ */
+function createArchivePayload(params) {
+    return {
+        ArchiveStateMachine: {
+            fiberId: params.fiberId,
+            targetSequenceNumber: params.targetSequenceNumber,
+        },
+    };
+}
+exports.createArchivePayload = createArchivePayload;
+/**
+ * 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);
+ * ```
+ */
+function createScriptPayload(params) {
+    return {
+        CreateScript: {
+            fiberId: params.fiberId,
+            scriptProgram: params.scriptProgram,
+            initialState: params.initialState ?? null,
+            accessControl: params.accessControl ?? { type: 'open' },
+        },
+    };
+}
+exports.createScriptPayload = createScriptPayload;
+/**
+ * Create an invoke script payload ready for signing.
+ *
+ * @param params - Invoke script parameters
+ * @returns An InvokeScript message ready for signing
+ */
+function createInvokeScriptPayload(params) {
+    return {
+        InvokeScript: {
+            fiberId: params.fiberId,
+            method: params.method,
+            args: params.args ?? {},
+            targetSequenceNumber: params.targetSequenceNumber,
+        },
+    };
+}
+exports.createInvokeScriptPayload = createInvokeScriptPayload;
+/**
+ * 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,
+ *   }),
+ * });
+ * ```
+ */
+async function signTransaction(message, privateKey) {
+    const proof = await (0, sign_js_1.signDataUpdate)(message, privateKey);
+    return {
+        value: message,
+        proofs: [proof],
+    };
+}
+exports.signTransaction = signTransaction;
+/**
+ * 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),
+ * });
+ * ```
+ */
+function createDataTransactionRequest(signed) {
+    return { data: signed, fee: null };
+}
+exports.createDataTransactionRequest = createDataTransactionRequest;
+/**
+ * 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
+ */
+async function addTransactionSignature(signed, privateKey) {
+    const newProof = await (0, sign_js_1.signDataUpdate)(signed.value, privateKey);
+    return {
+        value: signed.value,
+        proofs: [...signed.proofs, newProof],
+    };
+}
+exports.addTransactionSignature = addTransactionSignature;
+/**
+ * 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',
+ *   }),
+ * });
+ * ```
+ */
+function getPublicKeyForRegistration(privateKey) {
+    return (0, wallet_js_1.getPublicKeyId)(privateKey);
+}
+exports.getPublicKeyForRegistration = getPublicKeyForRegistration;

package/dist/cjs/ottochain/metagraph-client.js

@@ -11,6 +11,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MetagraphClient = void 0;
+const transaction_js_1 = require("../metakit/transaction.js");
 const client_js_1 = require("../metakit/network/client.js");
 const types_js_1 = require("../metakit/network/types.js");
 const snapshot_js_1 = require("./snapshot.js");
@@ -43,6 +44,9 @@ class MetagraphClient {
         if (config.dl1Url) {
             this.dl1 = new client_js_1.HttpClient(config.dl1Url, config.timeout);
         }
+        // Build DL1 client pool from dl1Urls (falls back to dl1Url if provided)
+        const urls = config.dl1Urls ?? (config.dl1Url ? [config.dl1Url] : []);
+        this.dl1Clients = urls.map((url) => new client_js_1.HttpClient(url, config.timeout));
     }
     // -------------------------------------------------------------------------
     // Custom routes (ML0 /data-application/v1/*)
@@ -300,5 +304,53 @@ class MetagraphClient {
         }
         return this.dl1.post('/data', signedData);
     }
+    /**
+     * 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);
+     * ```
+     */
+    async submitData(signed) {
+        if (this.dl1Clients.length === 0) {
+            throw new Error('dl1Url or dl1Urls is required for submitData');
+        }
+        const request = (0, transaction_js_1.createDataTransactionRequest)(signed);
+        if (this.dl1Clients.length === 1) {
+            return this.dl1Clients[0].post('/data', request);
+        }
+        // Try all DL1 nodes concurrently, return first success
+        const errors = [];
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            let pending = this.dl1Clients.length;
+            for (const client of this.dl1Clients) {
+                client.post('/data', request).then((result) => { if (!settled) {
+                    settled = true;
+                    resolve(result);
+                } }, (err) => {
+                    errors.push(err instanceof Error ? err : new Error(String(err)));
+                    pending--;
+                    if (pending === 0 && !settled) {
+                        reject(new Error('All DL1 nodes failed: ' + errors.map(e => e.message).join('; ')));
+                    }
+                });
+            }
+        });
+    }
 }
 exports.MetagraphClient = MetagraphClient;

package/dist/esm/index.js

@@ -31,3 +31,5 @@ validate, validatePrivateKey, validatePublicKey, validateAddress, validateKeyPai
 export * from './errors.js';
 // Validation schemas and helpers
 export * from './validation.js';
+// Ottochain metagraph client
+export { MetagraphClient } from './ottochain/metagraph-client.js';

package/dist/esm/metakit/index.js

@@ -28,3 +28,6 @@ export { TOKEN_DECIMALS } from './currency-types.js';
 export { createCurrencyTransaction, createCurrencyTransactionBatch, signCurrencyTransaction, verifyCurrencyTransaction, encodeCurrencyTransaction, hashCurrencyTransaction, getTransactionReference, isValidDagAddress, tokenToUnits, unitsToToken, } from './currency-transaction.js';
 // Network operations
 export { CurrencyL1Client, DataL1Client, HttpClient, NetworkError } from './network/index.js';
+// Transaction helpers for self-signed mode
+export { createTransitionPayload, createArchivePayload, createInvokeScriptPayload, signTransaction, addTransactionSignature, getPublicKeyForRegistration, } from './transaction.js';
+export { createStateMachinePayload, createScriptPayload, createDataTransactionRequest, } from './transaction.js';

package/dist/esm/metakit/transaction.js

@@ -0,0 +1,240 @@
+/**
+ * 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 { signDataUpdate } from './sign.js';
+import { getPublicKeyId } from './wallet.js';
+/**
+ * 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 function createStateMachinePayload(params) {
+    return {
+        CreateStateMachine: {
+            fiberId: params.fiberId,
+            definition: params.definition,
+            initialData: params.initialData ?? {},
+            ...(params.parentFiberId ? { parentFiberId: params.parentFiberId } : {}),
+        },
+    };
+}
+/**
+ * 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 function createTransitionPayload(params) {
+    return {
+        TransitionStateMachine: {
+            fiberId: params.fiberId,
+            eventName: params.eventName,
+            payload: params.payload ?? {},
+            targetSequenceNumber: params.targetSequenceNumber,
+        },
+    };
+}
+/**
+ * Create an archive payload ready for signing.
+ *
+ * @param params - Archive parameters
+ * @returns An ArchiveStateMachine message ready for signing
+ */
+export function createArchivePayload(params) {
+    return {
+        ArchiveStateMachine: {
+            fiberId: params.fiberId,
+            targetSequenceNumber: params.targetSequenceNumber,
+        },
+    };
+}
+/**
+ * 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 function createScriptPayload(params) {
+    return {
+        CreateScript: {
+            fiberId: params.fiberId,
+            scriptProgram: params.scriptProgram,
+            initialState: params.initialState ?? null,
+            accessControl: params.accessControl ?? { type: 'open' },
+        },
+    };
+}
+/**
+ * Create an invoke script payload ready for signing.
+ *
+ * @param params - Invoke script parameters
+ * @returns An InvokeScript message ready for signing
+ */
+export function createInvokeScriptPayload(params) {
+    return {
+        InvokeScript: {
+            fiberId: params.fiberId,
+            method: params.method,
+            args: params.args ?? {},
+            targetSequenceNumber: params.targetSequenceNumber,
+        },
+    };
+}
+/**
+ * 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 async function signTransaction(message, privateKey) {
+    const proof = await signDataUpdate(message, privateKey);
+    return {
+        value: message,
+        proofs: [proof],
+    };
+}
+/**
+ * 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 function createDataTransactionRequest(signed) {
+    return { data: signed, fee: null };
+}
+/**
+ * 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 async function addTransactionSignature(signed, privateKey) {
+    const newProof = await signDataUpdate(signed.value, privateKey);
+    return {
+        value: signed.value,
+        proofs: [...signed.proofs, newProof],
+    };
+}
+/**
+ * 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 function getPublicKeyForRegistration(privateKey) {
+    return getPublicKeyId(privateKey);
+}

package/dist/esm/ottochain/metagraph-client.js

@@ -8,6 +8,7 @@
  * @see modules/data_l1/src/main/scala/xyz/kd5ujc/data_l1/DataL1CustomRoutes.scala
  * @packageDocumentation
  */
+import { createDataTransactionRequest } from '../metakit/transaction.js';
 import { HttpClient } from '../metakit/network/client.js';
 import { NetworkError } from '../metakit/network/types.js';
 import { extractOnChainState } from './snapshot.js';
@@ -40,6 +41,9 @@ export class MetagraphClient {
         if (config.dl1Url) {
             this.dl1 = new HttpClient(config.dl1Url, config.timeout);
         }
+        // Build DL1 client pool from dl1Urls (falls back to dl1Url if provided)
+        const urls = config.dl1Urls ?? (config.dl1Url ? [config.dl1Url] : []);
+        this.dl1Clients = urls.map((url) => new HttpClient(url, config.timeout));
     }
     // -------------------------------------------------------------------------
     // Custom routes (ML0 /data-application/v1/*)
@@ -297,4 +301,52 @@ export class MetagraphClient {
         }
         return this.dl1.post('/data', signedData);
     }
+    /**
+     * 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);
+     * ```
+     */
+    async submitData(signed) {
+        if (this.dl1Clients.length === 0) {
+            throw new Error('dl1Url or dl1Urls is required for submitData');
+        }
+        const request = createDataTransactionRequest(signed);
+        if (this.dl1Clients.length === 1) {
+            return this.dl1Clients[0].post('/data', request);
+        }
+        // Try all DL1 nodes concurrently, return first success
+        const errors = [];
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            let pending = this.dl1Clients.length;
+            for (const client of this.dl1Clients) {
+                client.post('/data', request).then((result) => { if (!settled) {
+                    settled = true;
+                    resolve(result);
+                } }, (err) => {
+                    errors.push(err instanceof Error ? err : new Error(String(err)));
+                    pending--;
+                    if (pending === 0 && !settled) {
+                        reject(new Error('All DL1 nodes failed: ' + errors.map(e => e.message).join('; ')));
+                    }
+                });
+            }
+        });
+    }
 }

package/dist/types/index.d.ts

@@ -20,3 +20,5 @@ export { OttoChainError, NetworkError, ValidationError, SigningError, Transactio
 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 * from './errors.js';
 export * from './validation.js';
+export { MetagraphClient } from './ottochain/metagraph-client.js';
+export type { MetagraphClientConfig, Checkpoint, SubscribeOptions, FiberStateCallback, Unsubscribe } from './ottochain/metagraph-client.js';

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

@@ -21,3 +21,6 @@ export { TOKEN_DECIMALS } from './currency-types.js';
 export { createCurrencyTransaction, createCurrencyTransactionBatch, signCurrencyTransaction, verifyCurrencyTransaction, encodeCurrencyTransaction, hashCurrencyTransaction, getTransactionReference, isValidDagAddress, tokenToUnits, unitsToToken, } from './currency-transaction.js';
 export { CurrencyL1Client, DataL1Client, HttpClient, NetworkError } from './network/index.js';
 export type { NetworkConfig, RequestOptions, TransactionStatus, PendingTransaction, PostTransactionResponse, EstimateFeeResponse, PostDataResponse, } from './network/index.js';
+export { createTransitionPayload, createArchivePayload, createInvokeScriptPayload, signTransaction, addTransactionSignature, getPublicKeyForRegistration, } from './transaction.js';
+export { createStateMachinePayload, createScriptPayload, createDataTransactionRequest, } from './transaction.js';
+export type { CreateStateMachineParams, CreateStateMachineMessage, CreateScriptParams, CreateScriptMessage, DataTransactionRequest, TransitionParams, TransitionStateMachineMessage, ArchiveParams, ArchiveStateMachineMessage, InvokeScriptParams, InvokeScriptMessage, } from './transaction.js';

package/dist/types/metakit/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 './types.js';
+/**
+ * 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/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 '../metakit/types.js';
 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ottochain/sdk",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "TypeScript SDK for ottochain metagraph operations - signing, encoding, and network interactions",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",