lovewebconnection 0.0.0-stage → 0.2.1

package/dist/contract.js

@@ -0,0 +1,162 @@
+import { ChainMismatchError } from "./chain.js";
+async function callRead(client, contract, functionName, args) {
+    const result = await client.readContract({
+        address: contract.address,
+        abi: contract.abi,
+        functionName,
+        args,
+    });
+    return result;
+}
+/**
+ * ABI-typed read: functionName and args are checked against the ABI, and the
+ * return type is derived from the function's outputs.
+ */
+export async function readTyped(client, contract, functionName, ...args) {
+    return callRead(client, contract, functionName, args);
+}
+/** Bind a client and contract once, then call typed view functions directly. */
+export function createReader(client, contract) {
+    return (functionName, ...args) => callRead(client, contract, functionName, args);
+}
+export class ContractCallError extends Error {
+    address;
+    constructor(message, address) {
+        super(message);
+        this.name = "ContractCallError";
+        this.address = address;
+    }
+}
+/** Canonical Multicall3 deployment, present on most EVM chains. */
+export const MULTICALL3_ADDRESS = "0xcA11bde05977b3631167028862bE2a173976CA11";
+export const multicall3Abi = [
+    {
+        type: "function",
+        name: "getChainId",
+        stateMutability: "view",
+        inputs: [],
+        outputs: [{ name: "chainid", type: "uint256" }],
+    },
+    {
+        type: "function",
+        name: "getBlockNumber",
+        stateMutability: "view",
+        inputs: [],
+        outputs: [{ name: "blockNumber", type: "uint256" }],
+    },
+    {
+        type: "function",
+        name: "getCurrentBlockTimestamp",
+        stateMutability: "view",
+        inputs: [],
+        outputs: [{ name: "timestamp", type: "uint256" }],
+    },
+];
+/** Multicall3 batching surface: aggregate3 plus the native-balance helper. */
+export const multicall3BatchAbi = [
+    {
+        type: "function",
+        name: "aggregate3",
+        // aggregate3 is payable on-chain, but this kit only ever reaches it through
+        // eth_call, so it is declared view to stay inside the typed read surface.
+        stateMutability: "view",
+        inputs: [
+            {
+                name: "calls",
+                type: "tuple[]",
+                components: [
+                    { name: "target", type: "address" },
+                    { name: "allowFailure", type: "bool" },
+                    { name: "callData", type: "bytes" },
+                ],
+            },
+        ],
+        outputs: [
+            {
+                name: "returnData",
+                type: "tuple[]",
+                components: [
+                    { name: "success", type: "bool" },
+                    { name: "returnData", type: "bytes" },
+                ],
+            },
+        ],
+    },
+    {
+        type: "function",
+        name: "getEthBalance",
+        stateMutability: "view",
+        inputs: [{ name: "addr", type: "address" }],
+        outputs: [{ name: "balance", type: "uint256" }],
+    },
+];
+/**
+ * Example call against the configured chain: three view functions on Multicall3.
+ * These are self-verifying — getChainId() must agree with LWC_CHAIN_ID.
+ */
+export async function readExampleCall(client) {
+    const code = await client.getCode({ address: MULTICALL3_ADDRESS });
+    if (!code || code === "0x" || code === "0x0") {
+        throw new ContractCallError(`No contract deployed at ${MULTICALL3_ADDRESS} on this chain; Multicall3 is missing.`, MULTICALL3_ADDRESS);
+    }
+    const contract = { address: MULTICALL3_ADDRESS, abi: multicall3Abi };
+    const [chainId, blockNumber, blockTimestamp] = await Promise.all([
+        readTyped(client, contract, "getChainId"),
+        readTyped(client, contract, "getBlockNumber"),
+        readTyped(client, contract, "getCurrentBlockTimestamp"),
+    ]);
+    return { contract: MULTICALL3_ADDRESS, chainId, blockNumber, blockTimestamp };
+}
+/** Cross-check the contract's answer against the configured chain id. */
+export function assertContractChain(result, config) {
+    const reported = Number(result.chainId);
+    if (reported !== config.chainId) {
+        throw new ChainMismatchError(config.chainId, reported, "Multicall3 getChainId()");
+    }
+}
+function describeAge(seconds) {
+    if (seconds < 60)
+        return `${seconds}s`;
+    if (seconds < 3600)
+        return `${Math.floor(seconds / 60)}m`;
+    if (seconds < 86_400)
+        return `${Math.floor(seconds / 3600)}h`;
+    return `${Math.floor(seconds / 86_400)}d`;
+}
+export function formatExampleCall(result, config, latencyMs) {
+    const reported = Number(result.chainId);
+    const matches = reported === config.chainId;
+    const age = Math.max(0, Math.floor(Date.now() / 1000) - Number(result.blockTimestamp));
+    const rows = [
+        [
+            "getChainId()",
+            `${reported}  ${matches ? "matches LWC_CHAIN_ID" : `MISMATCH, expected ${config.chainId}`}`,
+        ],
+        ["getBlockNumber()", `${result.blockNumber}`],
+        ["getCurrentBlockTimestamp()", `${result.blockTimestamp} (${describeAge(age)} old)`],
+    ];
+    const width = Math.max(...rows.map(([label]) => label.length));
+    return [
+        "lwc — example contract call",
+        "",
+        `  contract      Multicall3 (${result.contract})`,
+        `  chain         ${config.name} (${config.chainId})`,
+        `  latency       ${latencyMs} ms`,
+        "",
+        ...rows.map(([label, value]) => `  ${label.padEnd(width)}  ${value}`),
+    ].join("\n");
+}
+export function toExampleCallJson(result, config, latencyMs) {
+    return {
+        ok: true,
+        contract: { name: "Multicall3", address: result.contract },
+        chain: { id: config.chainId, name: config.name },
+        latencyMs,
+        chainIdMatches: Number(result.chainId) === config.chainId,
+        calls: {
+            getChainId: result.chainId.toString(),
+            getBlockNumber: result.blockNumber.toString(),
+            getCurrentBlockTimestamp: result.blockTimestamp.toString(),
+        },
+    };
+}

package/dist/default-abi.d.ts

@@ -0,0 +1,53 @@
+/** Shown instead of a file path when the built-in ABI is used. */
+export declare const DEFAULT_ABI_LABEL = "built-in ERC-20";
+/**
+ * Standard ERC-20 surface, including the write functions so that asking for
+ * `transfer` gets the "only view and pure" error rather than "no function".
+ * Used whenever `--abi` is omitted, so plain token reads need no file.
+ */
+export declare const DEFAULT_ERC20_ABI: ({
+    type: "function";
+    name: string;
+    stateMutability: "view";
+    inputs: never[];
+    outputs: {
+        name: string;
+        type: "string";
+    }[];
+} | {
+    type: "function";
+    name: string;
+    stateMutability: "view";
+    inputs: never[];
+    outputs: {
+        name: string;
+        type: "uint8";
+    }[];
+} | {
+    type: "function";
+    name: string;
+    stateMutability: "view";
+    inputs: {
+        name: string;
+        type: "address";
+    }[];
+    outputs: {
+        name: string;
+        type: "uint256";
+    }[];
+} | {
+    type: "function";
+    name: string;
+    stateMutability: "nonpayable";
+    inputs: ({
+        name: string;
+        type: "address";
+    } | {
+        name: string;
+        type: "uint256";
+    })[];
+    outputs: {
+        name: string;
+        type: "bool";
+    }[];
+})[];

package/dist/default-abi.js

@@ -0,0 +1,85 @@
+/** Shown instead of a file path when the built-in ABI is used. */
+export const DEFAULT_ABI_LABEL = "built-in ERC-20";
+/**
+ * Standard ERC-20 surface, including the write functions so that asking for
+ * `transfer` gets the "only view and pure" error rather than "no function".
+ * Used whenever `--abi` is omitted, so plain token reads need no file.
+ */
+export const DEFAULT_ERC20_ABI = [
+    {
+        type: "function",
+        name: "name",
+        stateMutability: "view",
+        inputs: [],
+        outputs: [{ name: "", type: "string" }],
+    },
+    {
+        type: "function",
+        name: "symbol",
+        stateMutability: "view",
+        inputs: [],
+        outputs: [{ name: "", type: "string" }],
+    },
+    {
+        type: "function",
+        name: "decimals",
+        stateMutability: "view",
+        inputs: [],
+        outputs: [{ name: "", type: "uint8" }],
+    },
+    {
+        type: "function",
+        name: "totalSupply",
+        stateMutability: "view",
+        inputs: [],
+        outputs: [{ name: "", type: "uint256" }],
+    },
+    {
+        type: "function",
+        name: "balanceOf",
+        stateMutability: "view",
+        inputs: [{ name: "account", type: "address" }],
+        outputs: [{ name: "", type: "uint256" }],
+    },
+    {
+        type: "function",
+        name: "allowance",
+        stateMutability: "view",
+        inputs: [
+            { name: "owner", type: "address" },
+            { name: "spender", type: "address" },
+        ],
+        outputs: [{ name: "remaining", type: "uint256" }],
+    },
+    {
+        type: "function",
+        name: "transfer",
+        stateMutability: "nonpayable",
+        inputs: [
+            { name: "to", type: "address" },
+            { name: "amount", type: "uint256" },
+        ],
+        outputs: [{ name: "", type: "bool" }],
+    },
+    {
+        type: "function",
+        name: "approve",
+        stateMutability: "nonpayable",
+        inputs: [
+            { name: "spender", type: "address" },
+            { name: "amount", type: "uint256" },
+        ],
+        outputs: [{ name: "", type: "bool" }],
+    },
+    {
+        type: "function",
+        name: "transferFrom",
+        stateMutability: "nonpayable",
+        inputs: [
+            { name: "from", type: "address" },
+            { name: "to", type: "address" },
+            { name: "amount", type: "uint256" },
+        ],
+        outputs: [{ name: "", type: "bool" }],
+    },
+];

package/dist/history.d.ts

@@ -0,0 +1,83 @@
+import type { Address } from "viem";
+export declare class HistoryArgError extends Error {
+    constructor(message: string);
+}
+export interface HistoryArgs {
+    /** Watch log to read. */
+    path: string;
+    /** Where to write CSV, "-" for stdout, or null for the table. */
+    csvPath: string | null;
+    /** Only rows from this session id. */
+    session: string | null;
+    /** Pivot to one column per asset instead of one row per asset. */
+    wide: boolean;
+    /** Add a USD value column per asset to the wide CSV. */
+    usd: boolean;
+    /** Emit only the USD-valued asset columns, dropping the raw balances. */
+    usdOnly: boolean;
+}
+export declare function parseHistoryArgs(argv: string[]): HistoryArgs;
+export declare function readHistoryLog(path: string): string;
+export interface HistoryRow {
+    session: string;
+    /** Epoch milliseconds of the portfolio sample. */
+    at: number;
+    blockNumber: bigint | null;
+    asset: "native" | "token";
+    /** Token address, or null for the native balance. */
+    address: Address | null;
+    symbol: string;
+    label: string | null;
+    decimals: number | null;
+    balance: bigint | null;
+    /** Change since the previous sample; null for the first one. */
+    delta: bigint | null;
+    /** USD value at the sample's prices; null when the asset was not priced. */
+    usd: number | null;
+    /** Total of the priced holdings for this sample; null when nothing was priced. */
+    usdTotal: number | null;
+}
+export interface HistoryReport {
+    path: string;
+    rows: HistoryRow[];
+    /** Sessions that contributed rows, in log order. */
+    sessions: string[];
+    /** Portfolio samples that carried an error and no balances. */
+    skippedSamples: number;
+    /** Lines that were not JSON objects with a session id. */
+    skippedLines: number;
+}
+/**
+ * Turn the `portfolio` events of a watch NDJSON log into one row per asset per
+ * sample. A log holds every event type, so anything else is ignored; an errored
+ * sample has no balances and is counted instead of emitting blank rows.
+ */
+export declare function extractBalanceHistory(text: string, options?: {
+    session?: string | null;
+}): Omit<HistoryReport, "path">;
+export declare const HISTORY_CSV_HEADER: readonly ["session", "at", "block", "asset", "address", "symbol", "label", "decimals", "balance", "delta", "usd", "usd_total"];
+/**
+ * Long-format CSV: one row per asset per sample, with an ISO timestamp, the
+ * human-readable balance, and the change since the previous sample. Long format
+ * keeps the columns stable as tokens come and go, so a chart can group by
+ * `symbol` or `address`.
+ */
+export declare function historyCsv(report: Pick<HistoryReport, "rows">): string;
+/**
+ * Wide-format CSV: one row per portfolio sample and one column per asset, for
+ * tools that expect a single time series per column. `session`, `at`, and
+ * `block` stay first so samples from different runs remain distinguishable; an
+ * asset missing from a sample leaves its cell empty rather than repeating it.
+ * `usd_total` closes every row. With `options.usd`, a `SYMBOL (USD)` column
+ * follows each asset column and uses the values priced by `watch --usd`. With
+ * `options.usdOnly`, the raw balance columns are dropped and only those
+ * `SYMBOL (USD)` columns remain, for a purely value-based series.
+ */
+export declare function historyWideCsv(report: Pick<HistoryReport, "rows">, options?: {
+    usd?: boolean;
+    usdOnly?: boolean;
+}): string;
+/** Write the CSV, creating parent directories; a derived file is overwritten. */
+export declare function saveHistoryCsv(path: string, csv: string): void;
+export declare function formatHistory(report: HistoryReport): string;
+export declare function toHistoryJson(report: HistoryReport): Record<string, unknown>;