@lifi/compose-spec
Version:
Public wire-format types and schemas for Compose flows
352 lines (327 loc) • 14.6 kB
text/typescript
import type { Resource } from './resource.js';
/**
* Per-chain native-asset semantics.
*
* Most EVM chains have an ETH-style native gas coin sent via `msg.value` (the
* `evm-native` policy). A small number express their "native" coin as an
* ERC-20 token: on `as-erc20` chains (Tempo) no `msg.value` coin exists at
* all, while on `native-mirrored-erc20` chains (Arc) a real `msg.value` coin
* exists but is canonically routed through an ERC-20 facade that mirrors the
* native balance (`balanceOf == native wei / nativeScale`, with no balance
* storage of its own). Code that needs to lower or simulate a `Resource` of
* kind `"native"` should consult `getChainCapabilities(chainId)` rather than
* hardcoding chain IDs.
*
* The compose compiler uses this registry to transparently normalise native
* resources into ERC-20 resources on both ERC-20-canonical kinds at
* schema-decode time (see `normalizeResource` below and the `ResourceSchema`
* transform in `flowSchema.ts`).
*
* The two ERC-20-canonical kinds behave identically at the resource level —
* `hasErc20CanonicalNative` is the predicate for that shared behaviour. They
* diverge only at the simulation layer: `as-erc20` balances live in ordinary
* token storage, while `native-mirrored-erc20` balances have no storage slot
* and are satisfied by a native balance override scaled by `nativeScale`
* (see compose-core's `rewritePreconditions`).
*
* This union is the extension point for future native-asset policies. A chain
* with no canonical native asset would get a `reject-native` arm, under which a
* `{ kind: "native" }` resource becomes a validation error rather than being
* rewritten. No such chain exists yet, so the arm is not defined here.
*/
export type ChainCapabilities =
| { readonly kind: 'evm-native'; readonly chainId: number }
| {
readonly kind: 'as-erc20';
readonly chainId: number;
readonly nativeErc20: NativeErc20;
}
| {
readonly kind: 'native-mirrored-erc20';
readonly chainId: number;
readonly nativeErc20: NativeErc20;
/** Native wei per 1 unit of the facade ERC-20 (1e12 on Arc: 18-dec native, 6-dec USDC). */
readonly nativeScale: bigint;
};
export interface NativeErc20 {
readonly token: `0x${string}`;
readonly symbol: string;
readonly decimals: number;
}
/**
* The zero-address sentinel that represents the native gas coin on
* EVM-native chains. Exported so tests and call-sites can reference it
* by name rather than inlining 40 zeros.
*
* Inlined as a literal rather than imported from `@lifi/utils`: `compose-spec`
* is the wire-format leaf package and carries no `@lifi/*` dependencies
* (enforced by `scripts/check-compose-boundaries.mjs`).
*/
export const EVM_NATIVE_SENTINEL: `0x${string}` =
// eslint-disable-next-line @lifi/prefer-utils-constants -- compose-spec is the wire-format leaf and must not import @lifi/utils (enforced by scripts/check-compose-boundaries.mjs); the literal is intentional here
'0x0000000000000000000000000000000000000000';
/**
* Whether `address` is the EVM zero address (the native sentinel), compared
* case-insensitively. Inlined comparison: `compose-spec` cannot import
* `toAddress` from `@lifi/utils` (see `EVM_NATIVE_SENTINEL`).
*/
export const isZeroAddress = (address: string): boolean =>
address.toLowerCase() === EVM_NATIVE_SENTINEL.toLowerCase();
export const TEMPO_CHAIN_ID = 4217;
export const TEMPO_NATIVE_ERC20: NativeErc20 = {
token: '0x20C0000000000000000000000000000000000000',
symbol: 'pathUSD',
decimals: 6,
};
export const ARC_CHAIN_ID = 5042;
/**
* Arc's native gas coin is USDC (18-decimal wei at the EVM level). The USDC
* ERC-20 at this address is a view over native balances: `balanceOf` returns
* `native wei / 1e12` and has no balance storage slot; allowances live in
* regular storage. The composer interacts with USDC exclusively through this
* facade, never via `msg.value`.
*/
export const ARC_NATIVE_ERC20: NativeErc20 = {
token: '0x3600000000000000000000000000000000000000',
symbol: 'USDC',
decimals: 6,
};
// Derived from the facade's decimals so a decimal-count change cannot leave
// the scale silently wrong. Native wei is 18-decimal at the EVM level.
export const ARC_NATIVE_SCALE = 10n ** BigInt(18 - ARC_NATIVE_ERC20.decimals);
// Arc Testnet runs the same USDC facade at the same address, so it reuses
// Arc's facts rather than carrying a second copy.
export const ARC_TESTNET_CHAIN_ID = 5042002;
const REGISTRY: ReadonlyMap<number, ChainCapabilities> = new Map<
number,
ChainCapabilities
>([
[
TEMPO_CHAIN_ID,
{
kind: 'as-erc20',
chainId: TEMPO_CHAIN_ID,
nativeErc20: TEMPO_NATIVE_ERC20,
},
],
[
ARC_CHAIN_ID,
{
kind: 'native-mirrored-erc20',
chainId: ARC_CHAIN_ID,
nativeErc20: ARC_NATIVE_ERC20,
nativeScale: ARC_NATIVE_SCALE,
},
],
[
ARC_TESTNET_CHAIN_ID,
{
kind: 'native-mirrored-erc20',
chainId: ARC_TESTNET_CHAIN_ID,
nativeErc20: ARC_NATIVE_ERC20,
nativeScale: ARC_NATIVE_SCALE,
},
],
]);
/**
* Every chain with a non-default policy, in registration order. The registry
* itself stays private so runtime callers go through `getChainCapabilities`;
* this is the enumeration surface for tooling that must check *all* registered
* chains against an external source (the slot-finder parity spec), where
* scanning exported `*_CHAIN_ID` constants would silently miss a chain that
* skipped the naming convention.
*
* @internal Exported only so `chainCapabilitiesSlotFinderParity.spec.ts` can
* enumerate the registry. Not part of the package barrel.
*/
export const registeredChainCapabilities = (): readonly ChainCapabilities[] => [
...REGISTRY.values(),
];
export const getChainCapabilities = (chainId: number): ChainCapabilities =>
REGISTRY.get(chainId) ?? { kind: 'evm-native', chainId };
/**
* Structural fold over the `ChainCapabilities` union — the capabilities
* counterpart of `foldResource`/`foldRef`. Dispatches on `kind` and hands each
* case its narrowed fields, so consumers that must branch on the native-asset
* policy (e.g. compose-core's `rewritePreconditions`) do so through one
* combinator whose exhaustiveness the compiler enforces: adding a new arm to
* the union above turns every `foldChainCapabilities` call into a type error
* until it handles the new case.
*/
export const foldChainCapabilities = <R>(
caps: ChainCapabilities,
cases: {
readonly evmNative: (chainId: number) => R;
readonly asErc20: (nativeErc20: NativeErc20, chainId: number) => R;
readonly nativeMirroredErc20: (
nativeErc20: NativeErc20,
nativeScale: bigint,
chainId: number,
) => R;
},
): R => {
switch (caps.kind) {
case 'evm-native':
return cases.evmNative(caps.chainId);
case 'as-erc20':
return cases.asErc20(caps.nativeErc20, caps.chainId);
case 'native-mirrored-erc20':
return cases.nativeMirroredErc20(
caps.nativeErc20,
caps.nativeScale,
caps.chainId,
);
}
};
/**
* What a wire-level native-balance check (`nativeBalanceGte`) must become on
* a chain, decided once here from the native-asset policy:
*
* - `keep` — `evm-native`: the native read is the right read.
* - `rewrite` — `as-erc20` (Tempo): no `msg.value` coin exists, so the check
* becomes an `erc20BalanceGte` of `token`, the stand-in ERC-20. Amounts were
* always facade-denominated, so `minAmount` carries over verbatim.
* - `reject` — `native-mirrored-erc20` (Arc): a native read returns real
* 18-decimal wei, `nativeScale`× the facade's units, so no interpretation of
* `minAmount` is safe — reusing it on a facade read is 1e12 too strict for a
* wei-denominated check, keeping the native read lets a facade-denominated
* check pass 1e12 too easily. The check must be authored as
* `erc20BalanceGte` of the facade; `reason` says so.
*
* Consumers (the `AssertedPredicateSchema` decode and compose-core's derive
* backstop) are adapters over this result, so the unit rule lives in one place
* and the fold's exhaustiveness reaches every site.
*/
export type NativeCheckPolicy =
| { readonly kind: 'keep' }
| { readonly kind: 'rewrite'; readonly token: `0x${string}` }
| { readonly kind: 'reject'; readonly reason: string };
export const nativeCheckPolicy = (chainId: number): NativeCheckPolicy =>
foldChainCapabilities<NativeCheckPolicy>(getChainCapabilities(chainId), {
evmNative: () => ({ kind: 'keep' }),
asErc20: (nativeErc20) => ({ kind: 'rewrite', token: nativeErc20.token }),
nativeMirroredErc20: (nativeErc20) => ({
kind: 'reject',
reason:
`nativeBalanceGte is not accepted on chain ${chainId}: its canonical ` +
`native asset is an ERC-20 facade whose units differ from native wei — ` +
`author the check as erc20BalanceGte of ${nativeErc20.token}`,
}),
});
/**
* Exact-kind check for `as-erc20` (currently Tempo only) — the rare case that
* genuinely means "no `msg.value` coin exists on this chain". Most consumers
* want `hasErc20CanonicalNative` instead, which also covers
* `native-mirrored-erc20` chains (Arc), where the composer's ERC-20-only
* policy applies even though `msg.value` works. Code that must treat the two
* ERC-20-native kinds differently goes through `foldChainCapabilities` or
* `nativeCheckPolicy`, never a second exact-kind predicate.
*/
export const isAsErc20Chain = (chainId: number): boolean =>
getChainCapabilities(chainId).kind === 'as-erc20';
/**
* The chain's stand-in native ERC-20 when its canonical native asset is an
* ERC-20 (`as-erc20` and `native-mirrored-erc20`), `undefined` on plain
* `evm-native` chains. Module-local narrowing helper behind the exported
* predicates and rewrites below.
*/
const erc20CanonicalNative = (
caps: ChainCapabilities,
): NativeErc20 | undefined =>
caps.kind === 'as-erc20' || caps.kind === 'native-mirrored-erc20'
? caps.nativeErc20
: undefined;
/**
* Whether the chain's canonical native asset is an ERC-20 — true for both
* `as-erc20` chains (Tempo: no `msg.value` coin exists) and
* `native-mirrored-erc20` chains (Arc: `msg.value` exists but is never used).
* This is the predicate for the shared resource-level behaviour: native
* resources are rewritten to the ERC-20, native routing edges are dropped, and
* a surviving native resource is a compile error.
*/
export const hasErc20CanonicalNative = (chainId: number): boolean =>
erc20CanonicalNative(getChainCapabilities(chainId)) !== undefined;
/**
* The address that represents the chain's native asset.
*
* On EVM-native chains this is the zero-address sentinel `0x0…0`. On chains
* whose canonical native asset is an ERC-20 it is the chain's stand-in token
* (PathUSD on Tempo, the USDC facade on Arc).
*/
export const canonicalNativeAddress = (chainId: number): `0x${string}` =>
erc20CanonicalNative(getChainCapabilities(chainId))?.token ??
EVM_NATIVE_SENTINEL;
/**
* Whether `address` represents the native asset of `chainId`.
*
* On EVM-native chains, this is the case-insensitive zero-address check. On
* chains whose canonical native asset is an ERC-20, the literal zero address
* returns `false` — only the chain's stand-in ERC-20 address matches.
*/
export const isNativeAddressForChain = (
chainId: number,
address: string,
): boolean => {
const target = canonicalNativeAddress(chainId);
return address.toLowerCase() === target.toLowerCase();
};
/**
* Whether `address` on `chainId` is the genuine `msg.value`-style native coin:
* an `evm-native` chain's zero-address sentinel.
*
* This is the single predicate that gates `msg.value` semantics — choosing a
* `NativeBalance` over an `Erc20Balance` simulation requirement, and skipping
* the ERC-20 approval a native input would otherwise need. It returns `false`
* for every address on a chain whose canonical native asset is an ERC-20
* (including the zero sentinel): on `as-erc20` chains the "native" coin is a
* real ERC-20 moved via `transferFrom`, never `msg.value`, and on
* `native-mirrored-erc20` chains `msg.value` works but the composer's policy
* is to move the coin exclusively through the ERC-20 facade. Use this rather
* than re-deriving the check at call sites, and rather than
* `isNativeAddressForChain`, which returns `true` for the stand-in ERC-20
* (PathUSD on Tempo) and would wrongly route it to `msg.value`.
*/
export const isMsgValueNative = (chainId: number, address: string): boolean =>
!hasErc20CanonicalNative(chainId) && isZeroAddress(address);
/**
* Rewrite a single `Resource` according to its chain's capabilities.
*
* On chains with the default `evm-native` policy, every resource is returned
* unchanged. On chains whose canonical native asset is an ERC-20 (`as-erc20`
* Tempo, `native-mirrored-erc20` Arc), a resource of kind `"native"` is
* rewritten into the equivalent ERC-20 resource pointing at the chain's
* stand-in token (PathUSD on Tempo, the USDC facade on Arc).
*
* This is the rewrite primitive behind the `ResourceSchema` decode transform
* (see `flowSchema.ts`), which is THE chokepoint: it runs every time a
* `Resource` is parsed — flow inputs via `FlowSchema`, op configs via
* `decodeConfig` — so every downstream pass (`normalizeFlow`, `resolve`,
* `lower`, `simulate`) sees only ERC-20 resources on those chains.
*
* The function preserves referential identity when nothing changes (returns the
* input `r` unchanged on evm-native chains and for ERC-20 resources) and is
* idempotent: running it on an already-rewritten resource is a no-op.
*/
export const normalizeResource = (r: Resource): Resource => {
if (r.kind !== 'native') return r;
const erc20 = erc20CanonicalNative(getChainCapabilities(r.chainId));
if (erc20 === undefined) return r;
return {
kind: 'erc20',
chainId: r.chainId,
token: erc20.token,
};
};
/**
* Address-level counterpart of `normalizeResource` for wire fields that carry a
* native asset as a bare token string (a continuation outcome's `token`). On
* chains whose canonical native asset is an ERC-20, the native sentinel is
* rewritten to the chain's stand-in ERC-20; every other address passes through.
*/
export const normalizeNativeTokenAddress = (
token: string,
chainId: number,
): string =>
hasErc20CanonicalNative(chainId) && isZeroAddress(token)
? canonicalNativeAddress(chainId)
: token;