@skate-org/amm-evm-v2 0.4.1

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# @skate-org/amm-evm-v2
+
+## 0.4.1 — 2026-04-29
+
+- Flip DEV MegaETH RPC default to `https://mainnet.megaeth.com/rpc` (the
+  carrot.megaeth.com endpoint is no longer the canonical DEV RPC).
+- Extend DEV smoke to exercise `readPool` (kernel) and `readPeripheryPool`
+  (Arbitrum) against real contracts.
+
+## 0.4.0 — 2026-04-25
+
+- Phase 4: kernel + periphery event-decoding framework. `decodeKernel*`
+  / `decodePeriphery*` helpers; `watch*` event subscription utilities.
+
+## 0.3.0 — 2026-04-23
+
+- Phase 3: `readPool`, `readPeripheryPool`, `readPosition` reader helpers;
+  uniswap-v3 tick math; action submitters.
+
+## 0.2.0 — 2026-04-22
+
+- `createPublicClient` factory; `createDevConfig` for DEV mode tuples.
+
+## 0.1.0 — 2026-04-21
+
+- Initial scaffold: viem chain definitions, RPC defaults, `chain-clients.ts`.

package/README.md

@@ -0,0 +1,33 @@
+# @skate-org/amm-evm-v2
+
+EVM clients for the Skate AMM v2 SDK: viem chain definitions, kernel +
+periphery readers, uniswap-v3 tick math, action submitters, and the
+event-decoding framework.
+
+## Surface
+
+- `createPublicClient(chain, mode?)` — viem `PublicClient` factory with
+  Skate's RPC defaults baked in.
+- `createDevConfig({...})` — produces the DEV `{ mode, config }` tuple.
+- **Readers:** `readPool` (kernel side), `readPeripheryPool` (periphery
+  side), `readPosition`.
+- **Math:** uniswap-v3 tick / sqrt-price helpers.
+- **Events:** `decodeKernel*`, `decodePeriphery*`, `watch*` subscription
+  helpers.
+- **Submitters:** kernel + periphery action submission helpers.
+
+## Install
+
+```bash
+pnpm add @skate-org/amm-evm-v2
+```
+
+Peer deps: `@skate-org/amm-core-v2`, `@skate-org/amm-bindings`, `viem`.
+
+## DEV defaults (as of 2026-04-29)
+
+- MegaETH RPC: `https://mainnet.megaeth.com/rpc`
+- Kernel manager: `0x17B7207837e8884f7f687f1f4057751BDAf70a01`
+- USDC/USDT kernel pool: `0x2c23334eE3b030e6bacEDEDf7C511eEA08Cf7E7e`
+
+See `CHANGELOG.md` for version history.

package/dist/chain-clients.d.ts

@@ -0,0 +1,42 @@
+import { type Chain, type PublicClient, type Transport } from "viem";
+import { CHAIN, type EnvModeWithConfig } from "@skate-org/amm-core-v2";
+/**
+ * MegaETH chain definition — `@public`.
+ *
+ * Exported for callers who need to build their own viem `WalletClient` or
+ * `PublicClient` against the same chain the SDK uses internally (e.g. wallet
+ * integrations that construct a `WalletClient` ahead of calling
+ * `submitAction`). Prefer {@link getKernelPublicClient} when you just need a
+ * read client.
+ *
+ * viem ships a `megaeth` chain at id 4326, but with a different default RPC
+ * than the one Skate uses for kernel reads. Define locally so we control the
+ * RPC URL + block-explorer metadata and don't inherit unrelated op-stack
+ * contract addresses.
+ */
+export declare const megaethChain: Chain;
+/**
+ * Return a fresh `PublicClient` bound to the MegaETH kernel chain.
+ *
+ * MegaETH is the kernel chain for all environment modes (DEV/STAGING/
+ * PRODUCTION) in SDK v2. The `mode` parameter is accepted for API
+ * symmetry with the rest of the SDK and as a forward-compatible extension
+ * point (e.g. a future testnet kernel).
+ *
+ * Pure — no singletons, no caching. Pass a custom `transport` to override
+ * the default RPC (useful for tests and custom RPC providers).
+ */
+export declare function getKernelPublicClient(mode: EnvModeWithConfig, transport?: Transport): PublicClient;
+/**
+ * Return a fresh `PublicClient` for a source EVM chain (e.g. Arbitrum).
+ *
+ * Throws a descriptive `Error` when:
+ * - `chain` is not an EVM chain (per `vmTypeFromChain`); or
+ * - no viem chain definition is registered for `chain`; or
+ * - no default RPC URL is configured for `chain` and no `transport` override
+ *   was provided.
+ *
+ * Pure — no singletons, no caching.
+ */
+export declare function getSourcePublicClient(chain: CHAIN, mode: EnvModeWithConfig, transport?: Transport): PublicClient;
+//# sourceMappingURL=chain-clients.d.ts.map

package/dist/chain-clients.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain-clients.d.ts","sourceRoot":"","sources":["../src/chain-clients.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,KAAK,EACV,KAAK,YAAY,EACjB,KAAK,SAAS,EACf,MAAM,MAAM,CAAC;AAEd,OAAO,EAEL,KAAK,EAIL,KAAK,iBAAiB,EACvB,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,YAAY,EAAE,KAYzB,CAAC;AA4CH;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,iBAAiB,EACvB,SAAS,CAAC,EAAE,SAAS,GACpB,YAAY,CAKd;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,iBAAiB,EACvB,SAAS,CAAC,EAAE,SAAS,GACpB,YAAY,CAsBd"}

package/dist/devConfig.d.ts

@@ -0,0 +1,23 @@
+import type { DevModeConfig } from "@skate-org/amm-core-v2";
+/** Default DEV api endpoint — matches Phase 1's api client default. */
+export declare const DEFAULT_DEV_API_ENDPOINT = "https://dev.api.skatechain.org/amm-action-v2";
+/**
+ * Convenience factory for the `{ mode: "DEV"; config: DevModeConfig }` tuple.
+ *
+ * Reduces ceremony at call sites that want to override a single field (e.g.,
+ * `rpcEndpoints`) without reconstructing the full object:
+ *
+ * ```ts
+ * const mode = createDevConfig({
+ *   rpcEndpoints: { [CHAIN.MEGAETH]: "https://my-private-megaeth/rpc" },
+ * });
+ * submitAction(wallet, params, mode);
+ * ```
+ *
+ * Pass nothing to use all defaults.
+ */
+export declare function createDevConfig(overrides?: Partial<DevModeConfig>): {
+    mode: "DEV";
+    config: DevModeConfig;
+};
+//# sourceMappingURL=devConfig.d.ts.map

package/dist/devConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"devConfig.d.ts","sourceRoot":"","sources":["../src/devConfig.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAE5D,uEAAuE;AACvE,eAAO,MAAM,wBAAwB,iDACW,CAAC;AAEjD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAC7B,SAAS,GAAE,OAAO,CAAC,aAAa,CAAM,GACrC;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,aAAa,CAAA;CAAE,CAUxC"}

package/dist/errors.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Shared error types for the `@skate-org/amm-evm-v2` package.
+ *
+ * `EvmReadError` / `EvmWriteError` extend `SdkError` (from core) so callers
+ * can `instanceof SdkError` to catch any SDK-origin error without needing
+ * to know the specific subclass.
+ */
+import { SdkError } from "@skate-org/amm-core-v2";
+/** SDK-level error thrown when an EVM read reverts or decodes badly. */
+export declare class EvmReadError extends SdkError {
+    readonly name: string;
+    readonly functionName: string;
+    constructor(functionName: string, message: string, options?: ErrorOptions);
+}
+/**
+ * SDK-level error thrown when an EVM write (broadcast) fails.
+ *
+ * Symmetric with {@link EvmReadError}, but covers the write path: viem's
+ * `TransactionExecutionError`, `UserRejectedRequestError`,
+ * `ChainMismatchError`, `ChainDisconnectedError`, as well as submitter
+ * pre-flight guards (e.g. wrong-chain, missing account).
+ */
+export declare class EvmWriteError extends SdkError {
+    readonly name: string;
+    readonly functionName: string;
+    constructor(functionName: string, message: string, options?: ErrorOptions);
+}
+/**
+ * Wrap any error from an EVM read into `EvmReadError`. Viem always wraps
+ * revert-path errors in `ContractFunctionExecutionError` (see
+ * `viem/utils/errors/getContractError`), so we check both the outer name and
+ * the `.cause` chain for `ContractFunctionRevertedError` /
+ * `ContractFunctionZeroDataError`.
+ *
+ * Shared by `kernel/reader.ts` and `periphery/reader.ts` — depends only on
+ * `EvmReadError` and generic Error inspection (no reader-module imports), so
+ * it is safe from circular-import concerns.
+ */
+export declare function wrapReadError(err: unknown, functionName: string): EvmReadError;
+/**
+ * Wrap any error from an EVM write-path call (typically
+ * `WalletClient.sendTransaction`) into `EvmWriteError`.
+ *
+ * Any thrown error reaching a submitter is treated as a write failure. If
+ * we later want to differentiate known viem write errors
+ * (`TransactionExecutionError`, `UserRejectedRequestError`,
+ * `ChainMismatchError`, `ChainDisconnectedError`) from unknown errors —
+ * e.g. to prefix the message or re-throw unknowns raw — that dispatch goes
+ * here. Keeping the single-return shape until a concrete caller need
+ * surfaces.
+ */
+export declare function wrapWriteError(err: unknown, functionName: string): EvmWriteError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAElD,wEAAwE;AACxE,qBAAa,YAAa,SAAQ,QAAQ;IACxC,SAAkB,IAAI,EAAE,MAAM,CAAkB;IAChD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;gBAElB,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAI1E;AAED;;;;;;;GAOG;AACH,qBAAa,aAAc,SAAQ,QAAQ;IACzC,SAAkB,IAAI,EAAE,MAAM,CAAmB;IACjD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;gBAElB,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAI1E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,OAAO,EACZ,YAAY,EAAE,MAAM,GACnB,YAAY,CAmBd;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,OAAO,EACZ,YAAY,EAAE,MAAM,GACnB,aAAa,CAMf"}

package/dist/events/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./kernel";
+export * from "./periphery";
+export * from "./watch";
+//# sourceMappingURL=index.d.ts.map

package/dist/events/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/events/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC"}

package/dist/events/kernel.d.ts

@@ -0,0 +1,25 @@
+import { type Log } from "viem";
+/**
+ * Event names emitted by the Skate kernel's `KernelEventEmitter`, sourced
+ * directly from `@skate-org/amm-bindings`.
+ */
+export type KernelEventName = "Burn" | "Collect" | "CollectProtocol" | "IncreaseObservationCardinalityNext" | "Initialize" | "Mint" | "PeripheryPoolAdded" | "PeripheryPoolChanged" | "PoolCreated" | "PoolDescriptionUpdated" | "SetFeeProtocol" | "Swap";
+/** Exhaustive list of known kernel event names — same values as {@link KernelEventName}. */
+export declare const KERNEL_EVENT_NAMES: readonly KernelEventName[];
+/**
+ * A decoded kernel event — the event name, its named args, and the original
+ * viem `Log` for context (tx hash, block number, etc.).
+ */
+export interface KernelParsedEvent {
+    eventName: KernelEventName;
+    args: Record<string, unknown>;
+    log: Log;
+}
+/**
+ * Decode a viem `Log` emitted by the Skate kernel's `KernelEventEmitter`.
+ *
+ * Throws {@link EvmReadError} if the log's topic0 is not a known kernel event
+ * or if ABI decoding fails.
+ */
+export declare function parseKernelEventLog(log: Log): KernelParsedEvent;
+//# sourceMappingURL=kernel.d.ts.map

package/dist/events/kernel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kernel.d.ts","sourceRoot":"","sources":["../../src/events/kernel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,GAAG,EAAE,MAAM,MAAM,CAAC;AAIhD;;;GAGG;AACH,MAAM,MAAM,eAAe,GACvB,MAAM,GACN,SAAS,GACT,iBAAiB,GACjB,oCAAoC,GACpC,YAAY,GACZ,MAAM,GACN,oBAAoB,GACpB,sBAAsB,GACtB,aAAa,GACb,wBAAwB,GACxB,gBAAgB,GAChB,MAAM,CAAC;AAEX,4FAA4F;AAC5F,eAAO,MAAM,kBAAkB,EAAE,SAAS,eAAe,EAaxD,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,eAAe,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,GAAG,EAAE,GAAG,CAAC;CACV;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,GAAG,GAAG,iBAAiB,CAuB/D"}

package/dist/events/periphery.d.ts

@@ -0,0 +1,21 @@
+import { type Log } from "viem";
+/**
+ * Event names emitted by `PeripheryEventEmitter` on the source chain.
+ */
+export type PeripheryEventName = "AmountSettled" | "Burned" | "LiquidityDecreased" | "LiquidityIncreased" | "MintSettled" | "Minted" | "PoolCreated" | "PoolDeployed" | "Swapped" | "TransferredTo";
+/** Exhaustive list of known periphery event names. */
+export declare const PERIPHERY_EVENT_NAMES: readonly PeripheryEventName[];
+/** A decoded periphery event — name, named args, and the original viem `Log`. */
+export interface PeripheryParsedEvent {
+    eventName: PeripheryEventName;
+    args: Record<string, unknown>;
+    log: Log;
+}
+/**
+ * Decode a viem `Log` emitted by `PeripheryEventEmitter` on a source chain.
+ *
+ * Throws {@link EvmReadError} if the log's topic0 is not a known periphery
+ * event or if ABI decoding fails.
+ */
+export declare function parsePeripheryEventLog(log: Log): PeripheryParsedEvent;
+//# sourceMappingURL=periphery.d.ts.map

package/dist/events/periphery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"periphery.d.ts","sourceRoot":"","sources":["../../src/events/periphery.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,GAAG,EAAE,MAAM,MAAM,CAAC;AAIhD;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAC1B,eAAe,GACf,QAAQ,GACR,oBAAoB,GACpB,oBAAoB,GACpB,aAAa,GACb,QAAQ,GACR,aAAa,GACb,cAAc,GACd,SAAS,GACT,eAAe,CAAC;AAEpB,sDAAsD;AACtD,eAAO,MAAM,qBAAqB,EAAE,SAAS,kBAAkB,EAW9D,CAAC;AAEF,iFAAiF;AACjF,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,kBAAkB,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,GAAG,EAAE,GAAG,CAAC;CACV;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,GAAG,GAAG,oBAAoB,CAuBrE"}

package/dist/events/watch.d.ts

@@ -0,0 +1,23 @@
+import type { Address, PublicClient } from "viem";
+import { type KernelParsedEvent } from "./kernel";
+import { type PeripheryParsedEvent } from "./periphery";
+export interface EventSubscriptionOptions<E> {
+    /** Called for each decoded event. */
+    onEvent: (event: E) => void;
+    /** Called when a log fails to decode (subscription stays alive). */
+    onError?: (err: unknown) => void;
+}
+/**
+ * Subscribe to kernel events emitted by the `KernelEventEmitter` contract
+ * at `address`. Returns an unsubscribe function.
+ *
+ * Decode failures are surfaced via `opts.onError` (if provided) rather than
+ * throwing — the subscription continues.
+ */
+export declare function watchKernelEvents(client: PublicClient, address: Address, opts: EventSubscriptionOptions<KernelParsedEvent>): () => void;
+/**
+ * Subscribe to periphery events emitted by `PeripheryEventEmitter` at
+ * `address` on the source chain the `client` is connected to.
+ */
+export declare function watchPeripheryEvents(client: PublicClient, address: Address, opts: EventSubscriptionOptions<PeripheryParsedEvent>): () => void;
+//# sourceMappingURL=watch.d.ts.map

package/dist/events/watch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch.d.ts","sourceRoot":"","sources":["../../src/events/watch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAO,YAAY,EAAE,MAAM,MAAM,CAAC;AAKvD,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,UAAU,CAAC;AAClB,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,wBAAwB,CAAC,CAAC;IACzC,qCAAqC;IACrC,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IAC5B,oEAAoE;IACpE,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;CAClC;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,wBAAwB,CAAC,iBAAiB,CAAC,GAChD,MAAM,IAAI,CAcZ;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,wBAAwB,CAAC,oBAAoB,CAAC,GACnD,MAAM,IAAI,CAcZ"}