@ottochain/sdk 1.1.0 → 1.2.0

package/dist/esm/apps/oracles/state-machines/oracle.json

@@ -6,52 +6,36 @@
     },
     "states": {
         "UNREGISTERED": {
-            "id": {
-                "value": "UNREGISTERED"
-            },
+            "id": "UNREGISTERED",
             "isFinal": false,
             "metadata": null
         },
         "REGISTERED": {
-            "id": {
-                "value": "REGISTERED"
-            },
+            "id": "REGISTERED",
             "isFinal": false,
             "metadata": null
         },
         "ACTIVE": {
-            "id": {
-                "value": "ACTIVE"
-            },
+            "id": "ACTIVE",
             "isFinal": false,
             "metadata": null
         },
         "SLASHED": {
-            "id": {
-                "value": "SLASHED"
-            },
+            "id": "SLASHED",
             "isFinal": false,
             "metadata": null
         },
         "WITHDRAWN": {
-            "id": {
-                "value": "WITHDRAWN"
-            },
+            "id": "WITHDRAWN",
             "isFinal": true,
             "metadata": null
         }
     },
-    "initialState": {
-        "value": "UNREGISTERED"
-    },
+    "initialState": "UNREGISTERED",
     "transitions": [
         {
-            "from": {
-                "value": "UNREGISTERED"
-            },
-            "to": {
-                "value": "REGISTERED"
-            },
+            "from": "UNREGISTERED",
+            "to": "REGISTERED",
             "eventName": "register",
             "guard": {
                 ">=": [
@@ -95,12 +79,8 @@
             "dependencies": []
         },
         {
-            "from": {
-                "value": "REGISTERED"
-            },
-            "to": {
-                "value": "ACTIVE"
-            },
+            "from": "REGISTERED",
+            "to": "ACTIVE",
             "eventName": "activate",
             "guard": {
                 "or": [
@@ -135,12 +115,8 @@
             "dependencies": []
         },
         {
-            "from": {
-                "value": "ACTIVE"
-            },
-            "to": {
-                "value": "ACTIVE"
-            },
+            "from": "ACTIVE",
+            "to": "ACTIVE",
             "eventName": "add_stake",
             "guard": {
                 "and": [
@@ -189,12 +165,8 @@
             "dependencies": []
         },
         {
-            "from": {
-                "value": "ACTIVE"
-            },
-            "to": {
-                "value": "ACTIVE"
-            },
+            "from": "ACTIVE",
+            "to": "ACTIVE",
             "eventName": "record_resolution",
             "guard": {
                 "var": "event.marketId"
@@ -249,12 +221,8 @@
             "dependencies": []
         },
         {
-            "from": {
-                "value": "ACTIVE"
-            },
-            "to": {
-                "value": "SLASHED"
-            },
+            "from": "ACTIVE",
+            "to": "SLASHED",
             "eventName": "slash",
             "guard": {
                 "and": [
@@ -330,12 +298,8 @@
             "dependencies": []
         },
         {
-            "from": {
-                "value": "SLASHED"
-            },
-            "to": {
-                "value": "ACTIVE"
-            },
+            "from": "SLASHED",
+            "to": "ACTIVE",
             "eventName": "reactivate",
             "guard": {
                 "and": [
@@ -377,12 +341,8 @@
             "dependencies": []
         },
         {
-            "from": {
-                "value": "ACTIVE"
-            },
-            "to": {
-                "value": "WITHDRAWN"
-            },
+            "from": "ACTIVE",
+            "to": "WITHDRAWN",
             "eventName": "withdraw",
             "guard": {
                 "===": [
@@ -413,12 +373,8 @@
             "dependencies": []
         },
         {
-            "from": {
-                "value": "SLASHED"
-            },
-            "to": {
-                "value": "WITHDRAWN"
-            },
+            "from": "SLASHED",
+            "to": "WITHDRAWN",
             "eventName": "withdraw",
             "guard": {
                 "===": [

package/dist/esm/generated/index.js

@@ -7,7 +7,7 @@
  * @packageDocumentation
  *
  * NOTE — Dual-type architecture:
- * These generated types use proto conventions (FIBER_STATUS_ACTIVE, StateId { value } wrappers).
+ * These generated types use proto conventions (FIBER_STATUS_ACTIVE, plain string StateId).
  * The wire-format REST API types in src/ottochain/types.ts use plain strings ('Active').
  * Both coexist intentionally until PR #89 (Migrate fiber-engine to generated Scala types) merges.
  *

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/generated/index.d.ts

@@ -7,7 +7,7 @@
  * @packageDocumentation
  *
  * NOTE — Dual-type architecture:
- * These generated types use proto conventions (FIBER_STATUS_ACTIVE, StateId { value } wrappers).
+ * These generated types use proto conventions (FIBER_STATUS_ACTIVE, plain string StateId).
  * The wire-format REST API types in src/ottochain/types.ts use plain strings ('Active').
  * Both coexist intentionally until PR #89 (Migrate fiber-engine to generated Scala types) merges.
  *

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';