@aboutcircles/sdk-pathfinder 0.1.5 → 0.1.7

package/dist/flowMatrix.d.ts

@@ -1,6 +1,24 @@
-import type { FlowMatrix, TransferStep, Address } from '@aboutcircles/sdk-types';
+import type { FlowMatrix, TransferStep, Address, Hex } from '@aboutcircles/sdk-types';
 /**
  * Create an ABI‑ready FlowMatrix object from a list of TransferSteps.
+ *
+ * @param from - Sender address
+ * @param to - Receiver address
+ * @param value - Total value to transfer
+ * @param transfers - List of transfer steps
  */
 export declare function createFlowMatrix(from: Address, to: Address, value: bigint, transfers: TransferStep[]): FlowMatrix;
+/**
+ * Prepare flow matrix streams with hex-encoded data for ABI encoding
+ * Converts Uint8Array data to hex strings and adds optional txData to the first stream
+ *
+ * @param flowMatrix - The flow matrix to prepare
+ * @param txData - Optional transaction data to attach to the first stream
+ * @returns Array of streams with hex-encoded data ready for contract calls
+ */
+export declare function prepareFlowMatrixStreams(flowMatrix: FlowMatrix, txData?: Hex | Uint8Array): Array<{
+    sourceCoordinate: number;
+    flowEdgeIds: readonly number[];
+    data: Hex;
+}>;
 //# sourceMappingURL=flowMatrix.d.ts.map

package/dist/flowMatrix.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flowMatrix.d.ts","sourceRoot":"","sources":["../src/flowMatrix.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,OAAO,EAAgC,MAAM,yBAAyB,CAAC;AAG/G;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,OAAO,EACb,EAAE,EAAE,OAAO,EACX,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,YAAY,EAAE,GACxB,UAAU,CAmEZ"}
+{"version":3,"file":"flowMatrix.d.ts","sourceRoot":"","sources":["../src/flowMatrix.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,OAAO,EAAgC,GAAG,EAAE,MAAM,yBAAyB,CAAC;AAsDpH;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,OAAO,EACb,EAAE,EAAE,OAAO,EACX,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,YAAY,EAAE,GACxB,UAAU,CAiEZ;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,UAAU,EACtB,MAAM,CAAC,EAAE,GAAG,GAAG,UAAU,GACxB,KAAK,CAAC;IAAE,gBAAgB,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,IAAI,EAAE,GAAG,CAAA;CAAE,CAAC,CAiBhF"}

package/dist/flowMatrix.js

@@ -1,30 +1,73 @@
 import { packCoordinates, transformToFlowVertices } from './packing';
+import { bytesToHex } from '@aboutcircles/sdk-utils/bytes';
+/**
+ * Detect terminal edges using graph analysis
+ *
+ * Terminal edge detection algorithm:
+ * 1. Identify all edges that deliver value to the receiver
+ * 2. Check if there's a self-loop at the receiver (aggregate pattern)
+ * 3. If self-loop exists: it's the ONLY terminal edge (aggregates all incoming flows)
+ * 4. If no self-loop: all edges TO receiver are terminal (standard multi-path flow)
+ *
+ * This handles:
+ * - Aggregate mode: receiver collects tokens, then self-transfers to consolidate
+ * - Standard mode: multiple paths deliver directly to receiver
+ * - Mixed scenarios: correctly identifies final delivery point
+ */
+function detectTerminalEdges(transfers, receiver) {
+    const terminalEdges = new Set();
+    // Build adjacency info: track edges TO receiver and self-loops
+    const edgesToReceiver = [];
+    let selfLoopIndex = null;
+    transfers.forEach((t, index) => {
+        const fromLower = t.from.toLowerCase();
+        const toLower = t.to.toLowerCase();
+        // Check if this is a self-loop at the receiver
+        if (fromLower === receiver && toLower === receiver) {
+            selfLoopIndex = index;
+        }
+        // Check if this edge delivers to receiver
+        else if (toLower === receiver) {
+            edgesToReceiver.push(index);
+        }
+    });
+    // Decision logic:
+    // If self-loop exists, it's the aggregation edge (ONLY terminal)
+    // Otherwise, all edges delivering to receiver are terminal
+    if (selfLoopIndex !== null) {
+        terminalEdges.add(selfLoopIndex);
+    }
+    else {
+        edgesToReceiver.forEach(idx => terminalEdges.add(idx));
+    }
+    return terminalEdges;
+}
 /**
  * Create an ABI‑ready FlowMatrix object from a list of TransferSteps.
+ *
+ * @param from - Sender address
+ * @param to - Receiver address
+ * @param value - Total value to transfer
+ * @param transfers - List of transfer steps
  */
 export function createFlowMatrix(from, to, value, transfers) {
     const sender = from.toLowerCase();
     const receiver = to.toLowerCase();
     const { sorted: flowVertices, idx } = transformToFlowVertices(transfers, sender, receiver);
-    const flowEdges = transfers.map((t) => {
-        const isTerminal = t.to.toLowerCase() === receiver;
+    // Use graph analysis to detect terminal edges
+    const terminalEdgeIndices = detectTerminalEdges(transfers, receiver);
+    const flowEdges = transfers.map((t, index) => {
+        const isTerminal = terminalEdgeIndices.has(index);
         return {
             streamSinkId: isTerminal ? 1 : 0,
             amount: t.value
         };
     });
-    // Ensure at least one terminal edge
-    const hasTerminalEdge = flowEdges.some((e) => e.streamSinkId === 1);
-    if (!hasTerminalEdge) {
-        const lastEdgeIndex = transfers
-            .map((t) => t.to.toLowerCase())
-            .lastIndexOf(receiver);
-        const fallbackIndex = lastEdgeIndex === -1 ? flowEdges.length - 1 : lastEdgeIndex;
-        flowEdges[fallbackIndex].streamSinkId = 1;
+    // Validation: ensure at least one terminal edge exists
+    if (terminalEdgeIndices.size === 0) {
+        throw new Error(`No terminal edges detected. Flow must have at least one edge delivering to receiver ${receiver}`);
     }
-    const termEdgeIds = flowEdges
-        .map((e, i) => (e.streamSinkId === 1 ? i : -1))
-        .filter((i) => i !== -1);
+    const termEdgeIds = Array.from(terminalEdgeIndices);
     const streams = [
         {
             sourceCoordinate: idx[sender],
@@ -55,3 +98,27 @@ export function createFlowMatrix(from, to, value, transfers) {
         sourceCoordinate: idx[sender]
     };
 }
+/**
+ * Prepare flow matrix streams with hex-encoded data for ABI encoding
+ * Converts Uint8Array data to hex strings and adds optional txData to the first stream
+ *
+ * @param flowMatrix - The flow matrix to prepare
+ * @param txData - Optional transaction data to attach to the first stream
+ * @returns Array of streams with hex-encoded data ready for contract calls
+ */
+export function prepareFlowMatrixStreams(flowMatrix, txData) {
+    const streams = flowMatrix.streams.map((stream) => ({
+        sourceCoordinate: stream.sourceCoordinate,
+        flowEdgeIds: stream.flowEdgeIds,
+        data: stream.data instanceof Uint8Array
+            ? bytesToHex(stream.data)
+            : stream.data,
+    }));
+    // Attach txData to the first stream if provided
+    if (txData && streams.length > 0) {
+        streams[0].data = txData instanceof Uint8Array
+            ? bytesToHex(txData)
+            : txData;
+    }
+    return streams;
+}