@aboutcircles/sdk-pathfinder 0.1.0

package/dist/packing.d.ts

@@ -0,0 +1,13 @@
+import type { TransferStep } from '@aboutcircles/sdk-types';
+/**
+ * Pack a uint16 array into a hex string (big‑endian, no padding).
+ */
+export declare function packCoordinates(coords: number[]): string;
+/**
+ * Build a sorted vertex list plus index lookup for quick coordinate mapping.
+ */
+export declare function transformToFlowVertices(transfers: TransferStep[], from: string, to: string): {
+    sorted: string[];
+    idx: Record<string, number>;
+};
+//# sourceMappingURL=packing.d.ts.map

package/dist/packing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"packing.d.ts","sourceRoot":"","sources":["../src/packing.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAE5D;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAUxD;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,YAAY,EAAE,EACzB,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,GACT;IAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAsBnD"}

package/dist/packing.js

@@ -0,0 +1,38 @@
+import { bytesToHex } from '@aboutcircles/sdk-utils';
+/**
+ * Pack a uint16 array into a hex string (big‑endian, no padding).
+ */
+export function packCoordinates(coords) {
+    const bytes = new Uint8Array(coords.length * 2);
+    coords.forEach((c, i) => {
+        const hi = c >> 8;
+        const lo = c & 0xff;
+        const offset = 2 * i;
+        bytes[offset] = hi;
+        bytes[offset + 1] = lo;
+    });
+    return bytesToHex(bytes);
+}
+/**
+ * Build a sorted vertex list plus index lookup for quick coordinate mapping.
+ */
+export function transformToFlowVertices(transfers, from, to) {
+    const set = new Set([from.toLowerCase(), to.toLowerCase()]);
+    transfers.forEach((t) => {
+        set.add(t.from.toLowerCase());
+        set.add(t.to.toLowerCase());
+        set.add(t.tokenOwner.toLowerCase());
+    });
+    const sorted = [...set].sort((a, b) => {
+        const lhs = BigInt(a);
+        const rhs = BigInt(b);
+        const isLess = lhs < rhs;
+        const isGreater = lhs > rhs;
+        return isLess ? -1 : isGreater ? 1 : 0;
+    });
+    const idx = {};
+    sorted.forEach((addr, i) => {
+        idx[addr] = i;
+    });
+    return { sorted, idx };
+}

package/dist/path.d.ts

@@ -0,0 +1,14 @@
+import type { PathfindingResult, Address, TokenInfo } from '@aboutcircles/sdk-types';
+export declare function getTokenInfoMapFromPath(currentAvatar: Address, rpcUrl: string, transferPath: PathfindingResult): Promise<Map<string, TokenInfo>>;
+export declare function getWrappedTokensFromPath(transferPath: PathfindingResult, tokenInfoMap: Map<string, TokenInfo>): Record<string, [bigint, string]>;
+export declare function getExpectedUnwrappedTokenTotals(wrappedTotals: Record<string, [bigint, string]>, tokenInfoMap: Map<string, TokenInfo>): Record<string, [bigint, string]>;
+/**
+ * Replace wrapped token addresses with avatar addresses in the path
+ * This is used after unwrapping to reflect the actual tokens being transferred
+ */
+export declare function replaceWrappedTokensWithAvatars(path: PathfindingResult, tokenInfoMap: Map<string, TokenInfo>): PathfindingResult;
+export declare function replaceWrappedTokens(path: PathfindingResult, unwrapped: Record<string, [bigint, string]>): PathfindingResult;
+export declare function shrinkPathValues(path: PathfindingResult, sink: string, retainBps?: bigint): PathfindingResult;
+export declare function assertNoNettedFlowMismatch(path: PathfindingResult, overrideSource?: string, overrideSink?: string): void;
+export declare function computeNettedFlow(path: PathfindingResult): Map<string, bigint>;
+//# sourceMappingURL=path.d.ts.map

package/dist/path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../src/path.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAgB,OAAO,EAAE,SAAS,EAAyC,MAAM,yBAAyB,CAAC;AAI1I,wBAAsB,uBAAuB,CAC3C,aAAa,EAAE,OAAO,EACtB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,iBAAiB,GAC9B,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAwBjC;AAED,wBAAgB,wBAAwB,CACtC,YAAY,EAAE,iBAAiB,EAC/B,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,GACnC,MAAM,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAgBlC;AAED,wBAAgB,+BAA+B,CAC7C,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAC/C,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,GACnC,MAAM,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAiBlC;AAED;;;GAGG;AACH,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE,iBAAiB,EACvB,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,GACnC,iBAAiB,CAenB;AAED,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,iBAAiB,EACvB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAC1C,iBAAiB,CAmBnB;AAED,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,iBAAiB,EACvB,IAAI,EAAE,MAAM,EACZ,SAAS,GAAE,MAAgC,GAC1C,iBAAiB,CAuBnB;AAED,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,iBAAiB,EACvB,cAAc,CAAC,EAAE,MAAM,EACvB,YAAY,CAAC,EAAE,MAAM,GACpB,IAAI,CAkCN;AAmBD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,iBAAiB,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAU9E"}

package/dist/path.js

@@ -0,0 +1,153 @@
+import { CirclesRpc } from '@aboutcircles/sdk-rpc';
+import { CirclesConverter } from '@aboutcircles/sdk-utils';
+export async function getTokenInfoMapFromPath(currentAvatar, rpcUrl, transferPath) {
+    const tokenInfoMap = new Map();
+    const uniqueAddresses = new Set();
+    transferPath.transfers.forEach((t) => {
+        if (currentAvatar.toLowerCase() === t.from.toLowerCase())
+            uniqueAddresses.add(t.tokenOwner.toLowerCase());
+    });
+    const rpc = new CirclesRpc(rpcUrl);
+    const batch = await rpc.token.getTokenInfoBatch(Array.from(uniqueAddresses));
+    batch.forEach((info) => {
+        // @todo temporary fix
+        // @dev required to handle wrong returned tokenType from `circles_getTokenInfoBatch`
+        if (info.isWrapped && !info.isInflationary) {
+            info.tokenType = "CrcV2_ERC20WrapperDeployed_Demurraged";
+        }
+        tokenInfoMap.set(info.tokenAddress.toLowerCase(), info);
+    });
+    return tokenInfoMap;
+}
+export function getWrappedTokensFromPath(transferPath, tokenInfoMap) {
+    const wrappedTokensInPath = {};
+    transferPath.transfers.forEach((t) => {
+        const info = tokenInfoMap.get(t.tokenOwner.toLowerCase());
+        const isWrapper = info && info.tokenType.startsWith('CrcV2_ERC20WrapperDeployed');
+        if (isWrapper) {
+            if (!wrappedTokensInPath[t.tokenOwner]) {
+                wrappedTokensInPath[t.tokenOwner] = [BigInt(0), info.tokenType];
+            }
+            wrappedTokensInPath[t.tokenOwner][0] += BigInt(t.value);
+        }
+    });
+    return wrappedTokensInPath;
+}
+export function getExpectedUnwrappedTokenTotals(wrappedTotals, tokenInfoMap) {
+    const unwrapped = {};
+    Object.entries(wrappedTotals).forEach(([wrapperAddr, [total, type]]) => {
+        const info = tokenInfoMap.get(wrapperAddr.toLowerCase());
+        if (!info)
+            return;
+        if (type === 'CrcV2_ERC20WrapperDeployed_Demurraged') {
+            unwrapped[wrapperAddr] = [total, info.tokenOwner];
+        }
+        if (type === 'CrcV2_ERC20WrapperDeployed_Inflationary') {
+            unwrapped[wrapperAddr] = [CirclesConverter.attoStaticCirclesToAttoCircles(total), info.tokenOwner];
+        }
+    });
+    return unwrapped;
+}
+/**
+ * Replace wrapped token addresses with avatar addresses in the path
+ * This is used after unwrapping to reflect the actual tokens being transferred
+ */
+export function replaceWrappedTokensWithAvatars(path, tokenInfoMap) {
+    const rewritten = path.transfers.map((edge) => {
+        // Look up the token info for this tokenOwner
+        const tokenInfo = tokenInfoMap.get(edge.tokenOwner.toLowerCase());
+        // If we have token info and it's a wrapped token, replace with the underlying avatar
+        if (tokenInfo && tokenInfo.tokenType.startsWith('CrcV2_ERC20WrapperDeployed')) {
+            return { ...edge, tokenOwner: tokenInfo.tokenOwner };
+        }
+        // Keep the original tokenOwner if it's not wrapped
+        return edge;
+    });
+    return { ...path, transfers: rewritten };
+}
+export function replaceWrappedTokens(path, unwrapped) {
+    // Create a mapping from wrapped token addresses to avatar addresses
+    // unwrapped format: { wrapperAddress: [amount, avatarAddress] }
+    const wrapperToAvatar = {};
+    Object.entries(unwrapped).forEach(([wrapperAddr, [, avatarAddr]]) => {
+        wrapperToAvatar[wrapperAddr.toLowerCase()] = avatarAddr;
+    });
+    const rewritten = path.transfers.map((edge) => {
+        // Replace tokenOwner if it's a wrapped token address
+        // This changes which token is being transferred (from wrapped to underlying avatar token)
+        const tokenOwnerLower = edge.tokenOwner.toLowerCase();
+        const tokenOwner = (wrapperToAvatar[tokenOwnerLower] || edge.tokenOwner);
+        // Keep from and to addresses unchanged - they represent the actual flow participants
+        return { ...edge, tokenOwner };
+    });
+    return { ...path, transfers: rewritten };
+}
+export function shrinkPathValues(path, sink, retainBps = BigInt(999_999_999_999)) {
+    const incomingToSink = new Map();
+    const scaled = [];
+    const DENOM = BigInt(1_000_000_000_000);
+    path.transfers.forEach((edge) => {
+        const scaledValue = (BigInt(edge.value) * retainBps) / DENOM;
+        const isZero = scaledValue === BigInt(0);
+        if (isZero) {
+            return; // drop sub‑unit flows
+        }
+        scaled.push({ ...edge, value: scaledValue });
+        incomingToSink.set(edge.to, (incomingToSink.get(edge.to) ?? BigInt(0)) + scaledValue);
+    });
+    const maxFlow = sink ? incomingToSink.get(sink.toLowerCase()) ?? BigInt(0) : BigInt(0);
+    return {
+        maxFlow: maxFlow,
+        transfers: scaled
+    };
+}
+export function assertNoNettedFlowMismatch(path, overrideSource, overrideSink) {
+    const net = computeNettedFlow(path);
+    const { source, sink } = getSourceAndSink(path, overrideSource, overrideSink);
+    const endpointsCoincide = source === sink;
+    net.forEach((balance, addr) => {
+        /* ----------------------------------------------------------------
+         * Closed-loop case → every vertex must net to zero
+         * -------------------------------------------------------------- */
+        if (endpointsCoincide) {
+            if (balance !== BigInt(0)) {
+                throw new Error(`Vertex ${addr} is unbalanced: ${balance}`);
+            }
+            return; // done – nothing else to check for this addr
+        }
+        /* ----------------------------------------------------------------
+         * Ordinary DAG case → classic source / sink / intermediate rules
+         * -------------------------------------------------------------- */
+        const isSource = addr === source;
+        const isSink = addr === sink;
+        if (isSource && balance >= BigInt(0)) {
+            throw new Error(`Source ${addr} should be net negative, got ${balance}`);
+        }
+        if (isSink && balance <= BigInt(0)) {
+            throw new Error(`Sink ${addr} should be net positive, got ${balance}`);
+        }
+        const isIntermediate = !isSource && !isSink;
+        if (isIntermediate && balance !== BigInt(0)) {
+            throw new Error(`Vertex ${addr} is unbalanced: ${balance}`);
+        }
+    });
+}
+function getSourceAndSink(path, overrideSource, overrideSink) {
+    const senders = new Set(path.transfers.map((t) => t.from.toLowerCase()));
+    const receivers = new Set(path.transfers.map((t) => t.to.toLowerCase()));
+    const source = [...senders].find((a) => !receivers.has(a));
+    const sink = [...receivers].find((a) => !senders.has(a));
+    if (!(source ?? overrideSource) || !(sink ?? overrideSink)) {
+        throw new Error('Could not determine unique source / sink');
+    }
+    return { source: (source ?? overrideSource), sink: (sink ?? overrideSink) };
+}
+export function computeNettedFlow(path) {
+    const net = new Map();
+    path.transfers.forEach(({ from, to, value }) => {
+        const amount = BigInt(value);
+        net.set(from.toLowerCase(), (net.get(from.toLowerCase()) ?? BigInt(0)) - amount);
+        net.set(to.toLowerCase(), (net.get(to.toLowerCase()) ?? BigInt(0)) + amount);
+    });
+    return net;
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@aboutcircles/sdk-pathfinder",
+  "version": "0.1.0",
+  "description": "Pathfinding utilities for Circles SDK",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist && tsc --emitDeclarationOnly",
+    "dev": "tsc --build --watch",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "circles",
+    "pathfinding"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@aboutcircles/sdk-rpc": "*",
+    "@aboutcircles/sdk-types": "*",
+    "@aboutcircles/sdk-utils": "*",
+    "viem": "^2.38.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.4"
+  }
+}