@lifi/composer-sdk 0.5.0 → 0.6.0

package/src/examples/swapWithAllowRevert.ts

@@ -91,18 +91,28 @@ export const handleCompileResult = async (): Promise<void> => {
 
   if (result.status === 'success') {
     // Full success — transactionRequest includes gasLimit.
-    const { transactionRequest, userProxy, producedResources } = result;
+    const { transactionRequest, userProxy, outputs } = result;
     void transactionRequest;
     void userProxy;
-    void producedResources;
+    // Every linear resource output port appears in `outputs`, keyed
+    // `<nodeId>.<port>`. The swap's terminal output carries the amount.
+    const swapOut = outputs['swap.amountOut'];
+    void swapOut?.amount.estimate?.value; // simulated estimate on a 200
+    void swapOut?.amount.minimum?.value; // enforced floor, absent if none known
     return;
   }
 
   // Partial result — simulation reverted but a transaction is still available.
   // transactionRequest omits gasLimit; the caller must estimate gas themselves.
-  const { transactionRequest, simulationRevert, error } = result;
+  const { transactionRequest, outputs, simulationRevert, error } = result;
   void transactionRequest;
 
+  // Nothing was measured, so the estimate is a quote and the minimum is
+  // op-sourced (or absent) rather than a guard floor.
+  const swapOut = outputs['swap.amountOut'];
+  void swapOut?.amount.estimate?.value; // quoted on a 206
+  void swapOut?.amount.minimum?.value; // op/declared floor, absent if none
+
   // Inspect the revert reason.
   void simulationRevert.code;
   void simulationRevert.rawErrorBytes;

package/src/generated/config.generated.ts

@@ -60,6 +60,55 @@ export interface LifiSwapConfig {
   };
 }
 
+/**
+ * a string starting with "0x"
+ */
+export type StartsWith0X = string;
+/**
+ * a number between 0 and 1
+ */
+export type Between01 = number;
+
+export interface LifiBridgeConfig {
+  resourceOut:
+    | {
+        kind: 'native';
+        chainId: Positive;
+      }
+    | {
+        kind: 'erc20';
+        token: Address;
+        chainId: Positive;
+      };
+  destination: StartsWith0X;
+  slippage?: Between01;
+  timing?: {
+    swapStepTimingStrategies?: {
+      strategy: 'minWaitTime';
+      minWaitTimeMs: number;
+      startingExpectedResults: number;
+      reduceEveryMs: number;
+    }[];
+    routeTimingStrategies?: {
+      strategy: 'minWaitTime';
+      minWaitTimeMs: number;
+      startingExpectedResults: number;
+      reduceEveryMs: number;
+    }[];
+  };
+  bridges?: {
+    allow?: MaxItems50;
+    deny?: MaxItems50;
+    prefer?: MaxItems50;
+  };
+  exchanges?: {
+    allow?: MaxItems50;
+    deny?: MaxItems50;
+    prefer?: MaxItems50;
+  };
+  order?: 'FASTEST' | 'CHEAPEST';
+}
+
 export interface InvariantNumericConfig {
   op: 'gte' | 'gt' | 'lte' | 'lt' | 'eq' | 'neq';
   threshold: IntegerStringInput;
@@ -671,10 +720,6 @@ export type ContinuationAssertReadyConfig =
       comparator: 'gte' | 'eq' | 'lte';
       value: string;
     };
-/**
- * a string starting with "0x"
- */
-export type StartsWith0X = string;
 
 export interface LifiZapConfig {
   resourceOut:

package/src/generated/operations.generated.ts

@@ -44,6 +44,7 @@ import type {
   InvariantNeqConfig,
   InvariantNumericConfig,
   InvariantNumericInRangeConfig,
+  LifiBridgeConfig,
   LifiSwapConfig,
   LifiZapAsyncConfig,
   LifiZapConfig,
@@ -79,6 +80,15 @@ export interface LifiSwapArgs {
   readonly guards?: readonly TypedGuard<'unspentIn'>[];
 }
 
+/** Bridge tokens to another chain via the LI.FI aggregator API */
+export interface LifiBridgeArgs {
+  readonly bind: {
+    readonly amountIn: Bindable<'resource'>;
+  };
+  readonly config: LifiBridgeConfig;
+  readonly guards?: readonly TypedGuard<'unspentIn'>[];
+}
+
 /** Assert that an account holds at least a minimum token balance */
 export interface InvariantBalanceAtLeastArgs {
   readonly bind: {
@@ -574,6 +584,11 @@ export interface LifiSwapOutputs {
   readonly unspentIn: OutputHandle<'resource'>;
 }
 
+export interface LifiBridgeOutputs {
+  readonly amountOut: OutputHandle<'resource'>;
+  readonly unspentIn: OutputHandle<'resource'>;
+}
+
 export interface CoreAddOutputs {
   readonly result: OutputHandle<'uint256'>;
 }
@@ -767,6 +782,11 @@ export type GeneratedOps = {
   readonly lifi: {
     /** Swap tokens via the LI.FI aggregator API — original id: "lifi.swap" */
     readonly swap: (nodeId: string, args: LifiSwapArgs) => LifiSwapOutputs;
+    /** Bridge tokens to another chain via the LI.FI aggregator API — original id: "lifi.bridge" */
+    readonly bridge: (
+      nodeId: string,
+      args: LifiBridgeArgs,
+    ) => LifiBridgeOutputs;
     /** Route tokens into a DeFi protocol position via the edge catalog — original id: "lifi.zap" */
     readonly zap: (nodeId: string, args: LifiZapArgs) => LifiZapOutputs;
     /** Route tokens into a DeFi protocol position whose output becomes available after the initiating transaction settles — original id: "lifi.zapAsync" */
@@ -993,6 +1013,11 @@ export const bindGeneratedOps = (
         amountOut: 'resource',
         unspentIn: 'resource',
       } as const),
+    bridge: (nodeId: string, args: LifiBridgeArgs) =>
+      builder.call(nodeId, 'lifi.bridge', args, {
+        amountOut: 'resource',
+        unspentIn: 'resource',
+      } as const),
     zap: (nodeId: string, args: LifiZapArgs) =>
       builder.call(nodeId, 'lifi.zap', args, {
         amountOut: 'resource',

package/src/index.ts

@@ -31,6 +31,8 @@ export type {
 export type {
   ComposeError,
   ComposeErrorCode,
+  ComposeSdkOutdated,
+  ComposeServerOutdated,
   ComposePreparationOps,
 } from './errors.js';
 export type {
@@ -53,16 +55,25 @@ export type {
   InputSpec,
   MaterialiserConfigOf,
   MaterialiserInput,
+  OutputAmount,
+  Amount,
+  ConsumedOutput,
+  Delivery,
+  Estimate,
+  EstimateBasis,
+  Minimum,
+  MinimumBasis,
+  Output,
+  Outputs,
+  TerminalOutput,
   Precondition,
   PreconditionConfigOf,
   PriceImpact,
-  ProducedResource,
   Ref,
   Resource,
   RouteAmount,
   RouteAmountAll,
   RouteAmountExact,
-  SimulatedAmounts,
   SimulationPolicy,
   SimulationRevert,
   SolType,
@@ -90,7 +101,12 @@ export {
   SIMULATE_MAX_TRACKED_BALANCES,
   SIMULATE_MAX_REQUIREMENTS,
 } from '@lifi/compose-spec';
-export { isComposeError, isComposePreparationError } from './errors.js';
+export {
+  isComposeError,
+  isComposePreparationError,
+  isComposeSdkOutdatedError,
+  isComposeServerOutdatedError,
+} from './errors.js';
 
 export type {
   Bindable,
@@ -113,6 +129,8 @@ export { materialiser } from './run/inputs.js';
 export { buildSimulateRequest } from './run/simulate.js';
 export type { BuildSimulateRequestInput } from './run/simulate.js';
 
+export { terminalOutputs } from './outputs.js';
+
 export { createComposeSdk } from './sdk.js';
 export type { ComposeSdk, ComposeSdkOptions, FlowBuilder } from './sdk.js';
 

package/src/outputs.ts

@@ -0,0 +1,16 @@
+import type { Outputs, TerminalOutput } from '@lifi/compose-spec';
+
+/**
+ * The entries of `outputs` the caller actually receives: every port no later
+ * node spends, keyed `<nodeId>.<portName>` as on the wire. Consumed ports
+ * (intermediate amounts a later op takes as input) are dropped.
+ */
+export const terminalOutputs = (
+  outputs: Outputs,
+): Record<string, TerminalOutput> =>
+  Object.fromEntries(
+    Object.entries(outputs).filter(
+      (entry): entry is [string, TerminalOutput] =>
+        entry[1].role === 'terminal',
+    ),
+  );

package/src/responseSchemas.ts

@@ -90,12 +90,12 @@ export const parseSimulateResult = (body: unknown): SimulateResult | null => {
 
 /**
  * The validated members of an HTTP 206 partial compile envelope. `data` is
- * verified to be an object but kept untyped — compose-spec owns its full shape
- * (`ComposeCompilePartialData`) as a hand-authored type, so the caller narrows
- * it. `error` is fully validated.
+ * verified to be an object at runtime but left `unknown` here — compose-spec
+ * owns its full shape (`ComposeCompilePartialData`) as a hand-authored type, so
+ * the caller narrows it in one step. `error` is fully validated.
  */
 export interface CompilePartialEnvelope {
-  readonly data: Record<string, unknown>;
+  readonly data: unknown;
   readonly error: { readonly kind: string; readonly message: string };
 }
 
@@ -131,6 +131,9 @@ export interface ServerErrorBody {
     readonly kind?: string;
     readonly message?: string;
     readonly path?: string;
+    readonly sdkVersion?: string;
+    readonly serverVersion?: string;
+    readonly minimumSdkVersion?: string;
     readonly details?: SimulationRevert;
     readonly failedOps?: readonly ServerFailedPreparedOp[];
     readonly succeededOps?: readonly string[];
@@ -158,6 +161,9 @@ const serverErrorBodySchema = z.object({
       kind: z.string().optional(),
       message: z.string().optional(),
       path: z.string().optional(),
+      sdkVersion: z.string().optional(),
+      serverVersion: z.string().optional(),
+      minimumSdkVersion: z.string().optional(),
       details: z.custom<SimulationRevert>().optional(),
       failedOps: z.array(failedPreparedOpSchema).readonly().optional(),
       succeededOps: z.array(z.string()).readonly().optional(),

package/src/types.ts

@@ -48,14 +48,26 @@ export type AbiTypeToOutputKind<T extends string> = T extends SolType
   ? T
   : SolType;
 
+/**
+ * Phantom brand key for {@link TypedRef}.
+ *
+ * Declared, never assigned: it exists only so the type checker can tell a
+ * typed ref from an arbitrary `{ $ref }` object. Keying it on a `unique
+ * symbol` means no caller can produce one by writing an object literal.
+ */
+export declare const typedRefKind: unique symbol;
+
 /**
  * A typed `$ref` pointer carrying a phantom type parameter.
- * Extends `Ref` so it is accepted anywhere a plain `Ref` is.
- * The `__outputKind` field is never set at runtime — it exists only
- * for TypeScript's structural type checker to distinguish typed refs.
+ *
+ * On the wire, and at run time, this is exactly `{ $ref: string }` — the
+ * brand is erased. The brand is *required* in the type so a plain `Ref` does
+ * not satisfy `TypedRef` structurally, which is the contract `RefBindable`
+ * advertises: an untyped `{ $ref }` never enters a typed bind slot. Build one
+ * with `raw.ref<T>()`.
  */
 export interface TypedRef<T extends OutputKind = OutputKind> extends Ref {
-  readonly __outputKind?: T;
+  readonly [typedRefKind]: T;
 }
 
 /**