@ottochain/sdk 1.1.0 → 1.2.0

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.0",
+  "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",