@lifi/composer-sdk
Version:
Public Composer SDK for building and submitting flows
204 lines (188 loc) • 6.79 kB
text/typescript
/**
* Client-side reachability over the zap-pack catalog.
*
* `GET /compose/zap-packs` lists single routing edges. `POST /compose/route`
* chains up to the server's hop budget of them, so the set of routable pairs
* is the closure of the catalog, not the catalog itself. This module computes
* that closure locally with the planner's admissibility rule, so an integrator
* can offer every pair `route` connects without a request per pair.
*
* The rule, mirrored from the server's route search:
*
* - every edge except the last must leave its output in the proxy for the
* next edge to consume: no `availability`, no `recipient: 'required'`
* - the last edge must be synchronous, or `availability: 'future'` when the
* caller opts into `allowAsyncRoutes`
* - a route never visits the same token twice
*
* Amount bounds (`inAmountMin` / `inAmountMax`) on an intermediate edge
* cannot be checked without an amount, so a pair reported here is routable
* structurally, exactly as a listed edge is. Routes that open with a
* `lifi.swap` are not enumerable and are not reported. The server also
* drops blacklisted tokens as intermediates, which is server-side config
* this module cannot see, so a reported pair may still answer
* `no_route_error`.
*/
import type { ZapPackEdge, ZapPackOverview } from './discovery.js';
/** A token identified by address and chain. */
export interface TokenRef {
readonly address: string;
readonly chainId: number;
}
/** A from/to pair `POST /compose/route` can connect through the catalog. */
export interface RoutablePair {
readonly in: TokenRef;
readonly out: TokenRef;
/** Catalog edges on the shortest admissible route; `1` is a listed edge. */
readonly hops: number;
}
export interface ReachabilityOptions {
/**
* Hop budget. The server's `no_route_error` reports its effective value in
* `details.maxHops`; the deployment default is 2.
*/
readonly maxHops?: number;
/**
* Admit a route whose last edge has `availability: 'future'`. Mirrors the
* `allowAsyncRoutes` request option; such a pair is a `no_route_error`
* without it.
*/
readonly allowAsyncRoutes?: boolean;
}
export interface Reachability {
readonly maxHops: number;
/** Whether `route` can connect `from` to `to` through the catalog. */
readonly canRoute: (from: TokenRef, to: TokenRef) => boolean;
/** Every pair starting at `from`, shortest routes first. */
readonly routableFrom: (from: TokenRef) => readonly RoutablePair[];
/** Every routable pair in the catalog. */
readonly pairs: () => readonly RoutablePair[];
}
const DEFAULT_MAX_HOPS = 2;
const tokenKey = (token: TokenRef): string =>
`${token.chainId}:${token.address.toLowerCase()}`;
const isSync = (edge: ZapPackEdge): boolean => edge.availability === undefined;
// The output stays in the proxy, so a following edge can consume it.
const isProxyHeld = (edge: ZapPackEdge): boolean =>
isSync(edge) && edge.recipient !== 'required';
// One edge out of a frontier token. Records the pair it completes, and returns
// its output when a further hop may consume it (proxy-held) and no shorter
// path already expanded that token.
const visitEdge = ({
edge,
from,
depth,
sourceKey,
isTerminal,
found,
expanded,
}: {
readonly edge: ZapPackEdge;
readonly from: TokenRef;
readonly depth: number;
readonly sourceKey: string;
readonly isTerminal: (edge: ZapPackEdge) => boolean;
readonly found: Map<string, RoutablePair>;
readonly expanded: Set<string>;
}): TokenRef | undefined => {
const key = tokenKey(edge.out);
if (key === sourceKey) return undefined;
if (isTerminal(edge) && !found.has(key)) {
found.set(key, { in: from, out: edge.out, hops: depth });
}
if (!isProxyHeld(edge) || expanded.has(key)) return undefined;
expanded.add(key);
return edge.out;
};
// Every pair reachable from one token within `maxHops`, breadth-first so the
// recorded hop count is the shortest one.
const closureFrom = ({
byIn,
from,
maxHops,
isTerminal,
}: {
readonly byIn: ReadonlyMap<string, readonly ZapPackEdge[]>;
readonly from: TokenRef;
readonly maxHops: number;
readonly isTerminal: (edge: ZapPackEdge) => boolean;
}): Map<string, RoutablePair> => {
const sourceKey = tokenKey(from);
const found = new Map<string, RoutablePair>();
const expanded = new Set<string>([sourceKey]);
let frontier: readonly TokenRef[] = [from];
for (let depth = 1; depth <= maxHops && frontier.length > 0; depth++) {
const next: TokenRef[] = [];
for (const node of frontier) {
for (const edge of byIn.get(tokenKey(node)) ?? []) {
const out = visitEdge({
edge,
from,
depth,
sourceKey,
isTerminal,
found,
expanded,
});
if (out) next.push(out);
}
}
frontier = next;
}
return found;
};
const indexByIn = (
packs: readonly ZapPackOverview[],
): Map<string, ZapPackEdge[]> => {
const byIn = new Map<string, ZapPackEdge[]>();
for (const pack of packs) {
for (const edge of pack.edges) {
const key = tokenKey(edge.in);
const list = byIn.get(key);
if (list) list.push(edge);
else byIn.set(key, [edge]);
}
}
return byIn;
};
/**
* Builds a reachability index over the packs returned by
* {@link ComposeClient.getZapPacks}. Per-source closures are computed on
* first use and memoised, so `canRoute` on a handful of pairs stays cheap
* while `pairs()` enumerates everything.
*/
export const buildReachability = (
packs: readonly ZapPackOverview[],
options: ReachabilityOptions = {},
): Reachability => {
const maxHops = options.maxHops ?? DEFAULT_MAX_HOPS;
const allowAsync = options.allowAsyncRoutes ?? false;
const isTerminal = (edge: ZapPackEdge): boolean =>
isSync(edge) || (allowAsync && edge.availability === 'future');
const byIn = indexByIn(packs);
const memo = new Map<string, Map<string, RoutablePair>>();
const closure = (from: TokenRef): Map<string, RoutablePair> => {
const key = tokenKey(from);
const cached = memo.get(key);
if (cached) return cached;
const computed = closureFrom({ byIn, from, maxHops, isTerminal });
memo.set(key, computed);
return computed;
};
return {
maxHops,
canRoute: (from, to) => closure(from).has(tokenKey(to)),
routableFrom: (from) => [...closure(from).values()],
pairs: () => {
const sources = new Map<string, TokenRef>();
for (const pack of packs) {
for (const edge of pack.edges) sources.set(tokenKey(edge.in), edge.in);
}
const all: RoutablePair[] = [];
for (const source of sources.values()) {
all.push(...closure(source).values());
}
return all;
},
};
};