fourmm 0.1.0

package/dist/lib/const.d.ts

@@ -0,0 +1,165 @@
+/**
+ * On-chain constants for fourMM.
+ *
+ * These addresses are immutable and come from the Four.meme protocol
+ * documentation (docs/API-Documents.03-03-2026.md) and public BSC infrastructure.
+ *
+ * DO NOT read them from config — hardcoding catches misconfiguration at
+ * import time instead of at runtime.
+ */
+import type { Address } from 'viem';
+/** Legacy TokenManager (V1) — only for tokens created before 2024-09-05 */
+export declare const TOKEN_MANAGER_V1: Address;
+/** Current TokenManager (V2) — the default path for all new tokens */
+export declare const TOKEN_MANAGER_V2: Address;
+/**
+ * TokenManagerHelper3 — wrapper around V1/V2 that normalizes queries.
+ * Always prefer this for reads. Do not hardcode V1/V2 directly in commands.
+ */
+export declare const TOKEN_MANAGER_HELPER3: Address;
+/**
+ * AgentIdentifier — checks whether an address holds an Agent NFT.
+ * Tokens created by Agent wallets get aiCreator=true automatically.
+ */
+export declare const AGENT_IDENTIFIER: Address;
+/** PancakeSwap V2 Router on BSC mainnet */
+export declare const PANCAKE_V2_ROUTER: Address;
+/** PancakeSwap V2 Factory */
+export declare const PANCAKE_V2_FACTORY: Address;
+/**
+ * FourmemeMmRouter v2 — atomic router with reentrancy guard + approval hygiene.
+ *
+ * v2 changes: nonReentrant modifier, approval reset to 0 after sell,
+ * fee-on-transfer compat in volumePancake. BSCScan verified.
+ *
+ * v1 (0x5A3A9981...) is deprecated but still on-chain.
+ */
+export declare const FOURMEME_MM_ROUTER: Address;
+/**
+ * Get the router address.
+ *
+ * Now that the router is deployed, this is a simple passthrough.
+ * Kept as a function (not direct import) so commands have a single
+ * call site to update if we ever redeploy.
+ */
+export declare function requireRouter(): Address;
+export declare const CHAINS: {
+    readonly bsc: {
+        blockExplorers: {
+            readonly default: {
+                readonly name: "BscScan";
+                readonly url: "https://bscscan.com";
+                readonly apiUrl: "https://api.bscscan.com/api";
+            };
+        };
+        blockTime: 750;
+        contracts: {
+            readonly multicall3: {
+                readonly address: "0xca11bde05977b3631167028862be2a173976ca11";
+                readonly blockCreated: 15921452;
+            };
+        };
+        ensTlds?: readonly string[] | undefined;
+        id: 56;
+        name: "BNB Smart Chain";
+        nativeCurrency: {
+            readonly decimals: 18;
+            readonly name: "BNB";
+            readonly symbol: "BNB";
+        };
+        experimental_preconfirmationTime?: number | undefined | undefined;
+        rpcUrls: {
+            readonly default: {
+                readonly http: readonly ["https://56.rpc.thirdweb.com"];
+            };
+        };
+        sourceId?: number | undefined | undefined;
+        testnet?: boolean | undefined | undefined;
+        custom?: Record<string, unknown> | undefined;
+        extendSchema?: Record<string, unknown> | undefined;
+        fees?: import("viem").ChainFees<undefined> | undefined;
+        formatters?: undefined;
+        prepareTransactionRequest?: ((args: import("viem").PrepareTransactionRequestParameters, options: {
+            phase: "beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters";
+        }) => Promise<import("viem").PrepareTransactionRequestParameters>) | [fn: ((args: import("viem").PrepareTransactionRequestParameters, options: {
+            phase: "beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters";
+        }) => Promise<import("viem").PrepareTransactionRequestParameters>) | undefined, options: {
+            runAt: readonly ("beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters")[];
+        }] | undefined;
+        serializers?: import("viem").ChainSerializers<undefined, import("viem").TransactionSerializable> | undefined;
+        verifyHash?: ((client: import("viem").Client, parameters: import("viem").VerifyHashActionParameters) => Promise<import("viem").VerifyHashActionReturnType>) | undefined;
+    };
+    readonly 'bsc-testnet': {
+        blockExplorers: {
+            readonly default: {
+                readonly name: "BscScan";
+                readonly url: "https://testnet.bscscan.com";
+                readonly apiUrl: "https://api-testnet.bscscan.com/api";
+            };
+        };
+        blockTime?: number | undefined | undefined;
+        contracts: {
+            readonly multicall3: {
+                readonly address: "0xca11bde05977b3631167028862be2a173976ca11";
+                readonly blockCreated: 17422483;
+            };
+        };
+        ensTlds?: readonly string[] | undefined;
+        id: 97;
+        name: "BNB Smart Chain Testnet";
+        nativeCurrency: {
+            readonly decimals: 18;
+            readonly name: "BNB";
+            readonly symbol: "tBNB";
+        };
+        experimental_preconfirmationTime?: number | undefined | undefined;
+        rpcUrls: {
+            readonly default: {
+                readonly http: readonly ["https://data-seed-prebsc-1-s1.bnbchain.org:8545"];
+            };
+        };
+        sourceId?: number | undefined | undefined;
+        testnet: true;
+        custom?: Record<string, unknown> | undefined;
+        extendSchema?: Record<string, unknown> | undefined;
+        fees?: import("viem").ChainFees<undefined> | undefined;
+        formatters?: undefined;
+        prepareTransactionRequest?: ((args: import("viem").PrepareTransactionRequestParameters, options: {
+            phase: "beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters";
+        }) => Promise<import("viem").PrepareTransactionRequestParameters>) | [fn: ((args: import("viem").PrepareTransactionRequestParameters, options: {
+            phase: "beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters";
+        }) => Promise<import("viem").PrepareTransactionRequestParameters>) | undefined, options: {
+            runAt: readonly ("beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters")[];
+        }] | undefined;
+        serializers?: import("viem").ChainSerializers<undefined, import("viem").TransactionSerializable> | undefined;
+        verifyHash?: ((client: import("viem").Client, parameters: import("viem").VerifyHashActionParameters) => Promise<import("viem").VerifyHashActionReturnType>) | undefined;
+    };
+};
+export type SupportedChainName = keyof typeof CHAINS;
+/**
+ * Sentinel "address" for native BNB in fourMM's DataStore and routing layers.
+ *
+ * Important: BNB is the native currency of BSC and has no contract address.
+ * We use the zero address as a convention. This matches:
+ *   1. Four.meme's own usage — Helper3.getTokenInfo.quote returns address(0)
+ *      when the token is priced in BNB (confirmed via BSC mainnet reads)
+ *   2. The broader EVM convention for "native token placeholder"
+ *
+ * DO NOT confuse this with WBNB (0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c),
+ * which is a REAL ERC20 contract wrapping BNB. Using WBNB here would conflate
+ * native BNB transfers with WBNB token trades.
+ */
+export declare const NATIVE_BNB: Address;
+/** Wrapped BNB on BSC mainnet */
+export declare const WBNB: Address;
+/** BUSD on BSC mainnet */
+export declare const BUSD: Address;
+/** USDT (BEP-20) on BSC mainnet */
+export declare const USDT: Address;
+/**
+ * Return true if an address has the Four.meme native-token signature.
+ * Four.meme deploys all protocol-native tokens at addresses ending in `4444`.
+ * This is a cheap sanity check before making an RPC call.
+ */
+export declare function isFourmemeNativeAddress(address: string): boolean;
+//# sourceMappingURL=const.d.ts.map

package/dist/lib/const.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"const.d.ts","sourceRoot":"","sources":["../../src/lib/const.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAMnC,2EAA2E;AAC3E,eAAO,MAAM,gBAAgB,EAAE,OACe,CAAA;AAE9C,sEAAsE;AACtE,eAAO,MAAM,gBAAgB,EAAE,OACe,CAAA;AAE9C;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,OACU,CAAA;AAE9C;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,OACe,CAAA;AAM9C,2CAA2C;AAC3C,eAAO,MAAM,iBAAiB,EAAE,OACc,CAAA;AAE9C,6BAA6B;AAC7B,eAAO,MAAM,kBAAkB,EAAE,OACa,CAAA;AAM9C;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,EAAE,OACa,CAAA;AAE9C;;;;;;GAMG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAMD,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAGT,CAAA;AAEV,MAAM,MAAM,kBAAkB,GAAG,MAAM,OAAO,MAAM,CAAA;AAMpD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,UAAU,EAAE,OAAsD,CAAA;AAE/E,iCAAiC;AACjC,eAAO,MAAM,IAAI,EAAE,OAAsD,CAAA;AAEzE,0BAA0B;AAC1B,eAAO,MAAM,IAAI,EAAE,OAAsD,CAAA;AAEzE,mCAAmC;AACnC,eAAO,MAAM,IAAI,EAAE,OAAsD,CAAA;AAMzE;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEhE"}

package/dist/lib/const.js

@@ -0,0 +1,98 @@
+/**
+ * On-chain constants for fourMM.
+ *
+ * These addresses are immutable and come from the Four.meme protocol
+ * documentation (docs/API-Documents.03-03-2026.md) and public BSC infrastructure.
+ *
+ * DO NOT read them from config — hardcoding catches misconfiguration at
+ * import time instead of at runtime.
+ */
+import { bsc, bscTestnet } from 'viem/chains';
+// ============================================================
+// Four.meme (BSC mainnet)
+// ============================================================
+/** Legacy TokenManager (V1) — only for tokens created before 2024-09-05 */
+export const TOKEN_MANAGER_V1 = '0xEC4549caDcE5DA21Df6E6422d448034B5233bFbC';
+/** Current TokenManager (V2) — the default path for all new tokens */
+export const TOKEN_MANAGER_V2 = '0x5c952063c7fc8610FFDB798152D69F0B9550762b';
+/**
+ * TokenManagerHelper3 — wrapper around V1/V2 that normalizes queries.
+ * Always prefer this for reads. Do not hardcode V1/V2 directly in commands.
+ */
+export const TOKEN_MANAGER_HELPER3 = '0xF251F83e40a78868FcfA3FA4599Dad6494E46034';
+/**
+ * AgentIdentifier — checks whether an address holds an Agent NFT.
+ * Tokens created by Agent wallets get aiCreator=true automatically.
+ */
+export const AGENT_IDENTIFIER = '0x09B44A633de9F9EBF6FB9Bdd5b5629d3DD2cef13';
+// ============================================================
+// PancakeSwap (post-graduation)
+// ============================================================
+/** PancakeSwap V2 Router on BSC mainnet */
+export const PANCAKE_V2_ROUTER = '0x10ED43C718714eb63d5aA57B78B54704E256024E';
+/** PancakeSwap V2 Factory */
+export const PANCAKE_V2_FACTORY = '0xcA143Ce32Fe78f1f7019d7d551a6402fC5350c73';
+// ============================================================
+// fourMM contracts
+// ============================================================
+/**
+ * FourmemeMmRouter v2 — atomic router with reentrancy guard + approval hygiene.
+ *
+ * v2 changes: nonReentrant modifier, approval reset to 0 after sell,
+ * fee-on-transfer compat in volumePancake. BSCScan verified.
+ *
+ * v1 (0x5A3A9981...) is deprecated but still on-chain.
+ */
+export const FOURMEME_MM_ROUTER = '0xd62c2fd94176f98424af83e4b9a333d454b2216c';
+/**
+ * Get the router address.
+ *
+ * Now that the router is deployed, this is a simple passthrough.
+ * Kept as a function (not direct import) so commands have a single
+ * call site to update if we ever redeploy.
+ */
+export function requireRouter() {
+    return FOURMEME_MM_ROUTER;
+}
+// ============================================================
+// BSC chain configs
+// ============================================================
+export const CHAINS = {
+    bsc,
+    'bsc-testnet': bscTestnet,
+};
+// ============================================================
+// Common tokens
+// ============================================================
+/**
+ * Sentinel "address" for native BNB in fourMM's DataStore and routing layers.
+ *
+ * Important: BNB is the native currency of BSC and has no contract address.
+ * We use the zero address as a convention. This matches:
+ *   1. Four.meme's own usage — Helper3.getTokenInfo.quote returns address(0)
+ *      when the token is priced in BNB (confirmed via BSC mainnet reads)
+ *   2. The broader EVM convention for "native token placeholder"
+ *
+ * DO NOT confuse this with WBNB (0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c),
+ * which is a REAL ERC20 contract wrapping BNB. Using WBNB here would conflate
+ * native BNB transfers with WBNB token trades.
+ */
+export const NATIVE_BNB = '0x0000000000000000000000000000000000000000';
+/** Wrapped BNB on BSC mainnet */
+export const WBNB = '0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c';
+/** BUSD on BSC mainnet */
+export const BUSD = '0xe9e7CEA3DedcA5984780Bafc599bD69ADd087D56';
+/** USDT (BEP-20) on BSC mainnet */
+export const USDT = '0x55d398326f99059fF775485246999027B3197955';
+// ============================================================
+// Four.meme convention: all native tokens end in 4444
+// ============================================================
+/**
+ * Return true if an address has the Four.meme native-token signature.
+ * Four.meme deploys all protocol-native tokens at addresses ending in `4444`.
+ * This is a cheap sanity check before making an RPC call.
+ */
+export function isFourmemeNativeAddress(address) {
+    return address.toLowerCase().endsWith('4444');
+}
+//# sourceMappingURL=const.js.map

package/dist/lib/const.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"const.js","sourceRoot":"","sources":["../../src/lib/const.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAG7C,+DAA+D;AAC/D,0BAA0B;AAC1B,+DAA+D;AAE/D,2EAA2E;AAC3E,MAAM,CAAC,MAAM,gBAAgB,GAC3B,4CAA4C,CAAA;AAE9C,sEAAsE;AACtE,MAAM,CAAC,MAAM,gBAAgB,GAC3B,4CAA4C,CAAA;AAE9C;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAChC,4CAA4C,CAAA;AAE9C;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAC3B,4CAA4C,CAAA;AAE9C,+DAA+D;AAC/D,gCAAgC;AAChC,+DAA+D;AAE/D,2CAA2C;AAC3C,MAAM,CAAC,MAAM,iBAAiB,GAC5B,4CAA4C,CAAA;AAE9C,6BAA6B;AAC7B,MAAM,CAAC,MAAM,kBAAkB,GAC7B,4CAA4C,CAAA;AAE9C,+DAA+D;AAC/D,mBAAmB;AACnB,+DAA+D;AAE/D;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAC7B,4CAA4C,CAAA;AAE9C;;;;;;GAMG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAO,kBAAkB,CAAA;AAC3B,CAAC;AAED,+DAA+D;AAC/D,oBAAoB;AACpB,+DAA+D;AAE/D,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,GAAG;IACH,aAAa,EAAE,UAAU;CACjB,CAAA;AAIV,+DAA+D;AAC/D,gBAAgB;AAChB,+DAA+D;AAE/D;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,UAAU,GAAY,4CAA4C,CAAA;AAE/E,iCAAiC;AACjC,MAAM,CAAC,MAAM,IAAI,GAAY,4CAA4C,CAAA;AAEzE,0BAA0B;AAC1B,MAAM,CAAC,MAAM,IAAI,GAAY,4CAA4C,CAAA;AAEzE,mCAAmC;AACnC,MAAM,CAAC,MAAM,IAAI,GAAY,4CAA4C,CAAA;AAEzE,+DAA+D;AAC/D,sDAAsD;AACtD,+DAA+D;AAE/D;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAAe;IACrD,OAAO,OAAO,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;AAC/C,CAAC"}

package/dist/lib/env.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Secret / passphrase resolution helpers.
+ *
+ * Rule of thumb: passwords should NEVER live in command option schemas that
+ * agents can see in `--llms` or `--schema` output. They also shouldn't be
+ * global state (makes testing awkward and hides dependencies).
+ *
+ * Instead: commands accept an optional `--password` escape hatch (for local
+ * scripting), fall back to env vars, and pass the resolved password as an
+ * explicit function argument into the store layer.
+ */
+/** Resolve the in-house wallet store master password from arg or env */
+export declare function resolveFourmmPassword(explicit?: string | undefined): string | undefined;
+//# sourceMappingURL=env.d.ts.map

package/dist/lib/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/lib/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,wEAAwE;AACxE,wBAAgB,qBAAqB,CACnC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,GAC5B,MAAM,GAAG,SAAS,CAGpB"}

package/dist/lib/env.js

@@ -0,0 +1,18 @@
+/**
+ * Secret / passphrase resolution helpers.
+ *
+ * Rule of thumb: passwords should NEVER live in command option schemas that
+ * agents can see in `--llms` or `--schema` output. They also shouldn't be
+ * global state (makes testing awkward and hides dependencies).
+ *
+ * Instead: commands accept an optional `--password` escape hatch (for local
+ * scripting), fall back to env vars, and pass the resolved password as an
+ * explicit function argument into the store layer.
+ */
+/** Resolve the in-house wallet store master password from arg or env */
+export function resolveFourmmPassword(explicit) {
+    if (explicit)
+        return explicit;
+    return process.env.FOURMM_PASSWORD || undefined;
+}
+//# sourceMappingURL=env.js.map

package/dist/lib/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/lib/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,wEAAwE;AACxE,MAAM,UAAU,qBAAqB,CACnC,QAA6B;IAE7B,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAA;IAC7B,OAAO,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,SAAS,CAAA;AACjD,CAAC"}

package/dist/lib/guards.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Entry guards for trade / tools / transfer commands.
+ *
+ * The core invariant: every command that touches trading logic for a specific
+ * token MUST call `assertSupportedToken(ca)` before doing any signing or
+ * on-chain write. This is how fourMM enforces "TaxToken and X Mode are out of
+ * scope" without having to repeat the check inside each command body.
+ *
+ * Failure mode: `assertSupportedToken` throws `UnsupportedTokenError`, which
+ * command handlers can catch and return as a structured `c.error({...})`
+ * with a clean error code.
+ */
+import type { Address } from 'viem';
+import { identifyToken, type IdentifyResult } from './identify.js';
+import type { TokenVariant } from '../datastore/types.js';
+/** The two variants that fourMM actively supports */
+export type SupportedVariant = Extract<TokenVariant, 'standard' | 'anti-sniper-fee'>;
+export declare class UnsupportedTokenError extends Error {
+    readonly variant: TokenVariant;
+    readonly ca: Address;
+    readonly reason: string;
+    readonly code: "UNSUPPORTED_TOKEN";
+    constructor(variant: TokenVariant, ca: Address, reason: string);
+}
+export declare class TokenNotFoundError extends Error {
+    readonly ca: Address;
+    readonly code: "TOKEN_NOT_FOUND";
+    constructor(ca: Address);
+}
+/**
+ * Throw if the token is a variant fourMM does not support OR the API says the
+ * token isn't on Four.meme at all.
+ *
+ * Returns the identification result so callers can avoid a second API call
+ * (e.g. `trade buy` can reuse `result.raw` for future slippage estimates).
+ *
+ * Network failures (source=fallback-network) are NOT treated as hard errors:
+ * we default to `standard` and let the downstream RPC layer (Helper3) be
+ * the arbiter. This keeps the CLI usable when Four.meme's API is degraded.
+ */
+export declare function assertSupportedToken(ca: Address, options?: Parameters<typeof identifyToken>[1]): Promise<IdentifyResult & {
+    variant: SupportedVariant;
+}>;
+//# sourceMappingURL=guards.d.ts.map

package/dist/lib/guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../src/lib/guards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AACnC,OAAO,EAAE,aAAa,EAAE,KAAK,cAAc,EAAE,MAAM,eAAe,CAAA;AAClE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAEzD,qDAAqD;AACrD,MAAM,MAAM,gBAAgB,GAAG,OAAO,CAAC,YAAY,EAAE,UAAU,GAAG,iBAAiB,CAAC,CAAA;AAEpF,qBAAa,qBAAsB,SAAQ,KAAK;IAG5C,QAAQ,CAAC,OAAO,EAAE,YAAY;IAC9B,QAAQ,CAAC,EAAE,EAAE,OAAO;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM;IAJzB,QAAQ,CAAC,IAAI,EAAG,mBAAmB,CAAS;gBAEjC,OAAO,EAAE,YAAY,EACrB,EAAE,EAAE,OAAO,EACX,MAAM,EAAE,MAAM;CAK1B;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAE/B,QAAQ,CAAC,EAAE,EAAE,OAAO;IADhC,QAAQ,CAAC,IAAI,EAAG,iBAAiB,CAAS;gBACrB,EAAE,EAAE,OAAO;CAOjC;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,oBAAoB,CACxC,EAAE,EAAE,OAAO,EACX,OAAO,CAAC,EAAE,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC,CAAC,CAAC,GAC5C,OAAO,CAAC,cAAc,GAAG;IAAE,OAAO,EAAE,gBAAgB,CAAA;CAAE,CAAC,CA4BzD"}

package/dist/lib/guards.js

@@ -0,0 +1,65 @@
+/**
+ * Entry guards for trade / tools / transfer commands.
+ *
+ * The core invariant: every command that touches trading logic for a specific
+ * token MUST call `assertSupportedToken(ca)` before doing any signing or
+ * on-chain write. This is how fourMM enforces "TaxToken and X Mode are out of
+ * scope" without having to repeat the check inside each command body.
+ *
+ * Failure mode: `assertSupportedToken` throws `UnsupportedTokenError`, which
+ * command handlers can catch and return as a structured `c.error({...})`
+ * with a clean error code.
+ */
+import { identifyToken } from './identify.js';
+export class UnsupportedTokenError extends Error {
+    variant;
+    ca;
+    reason;
+    code = 'UNSUPPORTED_TOKEN';
+    constructor(variant, ca, reason) {
+        super(`${variant} ${ca}: ${reason}`);
+        this.variant = variant;
+        this.ca = ca;
+        this.reason = reason;
+        this.name = 'UnsupportedTokenError';
+    }
+}
+export class TokenNotFoundError extends Error {
+    ca;
+    code = 'TOKEN_NOT_FOUND';
+    constructor(ca) {
+        super(`Token ${ca} is not registered with Four.meme (API returned not-found). ` +
+            `Either the address is wrong or the token predates the API we query.`);
+        this.ca = ca;
+        this.name = 'TokenNotFoundError';
+    }
+}
+/**
+ * Throw if the token is a variant fourMM does not support OR the API says the
+ * token isn't on Four.meme at all.
+ *
+ * Returns the identification result so callers can avoid a second API call
+ * (e.g. `trade buy` can reuse `result.raw` for future slippage estimates).
+ *
+ * Network failures (source=fallback-network) are NOT treated as hard errors:
+ * we default to `standard` and let the downstream RPC layer (Helper3) be
+ * the arbiter. This keeps the CLI usable when Four.meme's API is degraded.
+ */
+export async function assertSupportedToken(ca, options) {
+    const result = await identifyToken(ca, options);
+    if (result.source === 'not-found') {
+        throw new TokenNotFoundError(ca);
+    }
+    if (result.variant === 'tax-token') {
+        throw new UnsupportedTokenError(result.variant, ca, 'TaxToken is not supported. fourMM refuses to market-make on TaxTokens — ' +
+            'each round-trip costs 2× the fee rate (e.g. 10% on a 5% tax token). ' +
+            'This is by design.');
+    }
+    if (result.variant === 'x-mode') {
+        throw new UnsupportedTokenError(result.variant, ca, 'X Mode token is not supported. fourMM does not implement the exclusive ' +
+            'Binance MPC Wallet purchase path (buyToken(bytes args, uint256 time, bytes signature)).');
+    }
+    // narrow type by returning a new object with the supported variant
+    return { ...result, variant: result.variant };
+}
+//# sourceMappingURL=guards.js.map

package/dist/lib/guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.js","sourceRoot":"","sources":["../../src/lib/guards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,aAAa,EAAuB,MAAM,eAAe,CAAA;AAMlE,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAGnC;IACA;IACA;IAJF,IAAI,GAAG,mBAA4B,CAAA;IAC5C,YACW,OAAqB,EACrB,EAAW,EACX,MAAc;QAEvB,KAAK,CAAC,GAAG,OAAO,IAAI,EAAE,KAAK,MAAM,EAAE,CAAC,CAAA;QAJ3B,YAAO,GAAP,OAAO,CAAc;QACrB,OAAE,GAAF,EAAE,CAAS;QACX,WAAM,GAAN,MAAM,CAAQ;QAGvB,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAA;IACrC,CAAC;CACF;AAED,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAEtB;IADZ,IAAI,GAAG,iBAA0B,CAAA;IAC1C,YAAqB,EAAW;QAC9B,KAAK,CACH,SAAS,EAAE,8DAA8D;YACvE,qEAAqE,CACxE,CAAA;QAJkB,OAAE,GAAF,EAAE,CAAS;QAK9B,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAA;IAClC,CAAC;CACF;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,EAAW,EACX,OAA6C;IAE7C,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,EAAE,EAAE,OAAO,CAAC,CAAA;IAE/C,IAAI,MAAM,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;QAClC,MAAM,IAAI,kBAAkB,CAAC,EAAE,CAAC,CAAA;IAClC,CAAC;IAED,IAAI,MAAM,CAAC,OAAO,KAAK,WAAW,EAAE,CAAC;QACnC,MAAM,IAAI,qBAAqB,CAC7B,MAAM,CAAC,OAAO,EACd,EAAE,EACF,0EAA0E;YACxE,sEAAsE;YACtE,oBAAoB,CACvB,CAAA;IACH,CAAC;IAED,IAAI,MAAM,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QAChC,MAAM,IAAI,qBAAqB,CAC7B,MAAM,CAAC,OAAO,EACd,EAAE,EACF,yEAAyE;YACvE,yFAAyF,CAC5F,CAAA;IACH,CAAC;IAED,mEAAmE;IACnE,OAAO,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAA;AAC/C,CAAC"}

package/dist/lib/identify.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Token variant identification.
+ *
+ * Four.meme has four variants: standard / anti-sniper-fee / tax-token / x-mode.
+ *
+ * We detect the variant via Four.meme's public REST API
+ * (`https://four.meme/meme-api/v1/private/token/get?address=...`). The endpoint
+ * is public despite its "/private/" path segment — it's a read API for token
+ * metadata and requires no auth.
+ *
+ * Why not on-chain? The documented method is to read
+ * `TokenManager2._tokenInfos[token].template` and check specific bits
+ * (creatorType == 5 → tax-token, bit 0x10000 → x-mode). But the full
+ * TokenInfo + TokenInfoEx1 struct layout isn't published, and reverse-
+ * engineering struct encoding is fragile. The REST API gives us the same
+ * signals with documented field names and typed JSON.
+ *
+ * Three response states (carried in `IdentifyResult.source`):
+ *
+ *   - `api`                → got a real classification from the API
+ *   - `not-found`          → API responded with code != 0 or data === null,
+ *                             meaning the token isn't on Four.meme at all
+ *   - `fallback-network`   → HTTP / timeout / connection error, couldn't tell
+ *
+ * Commands that need strict guarantees (`trade buy`, `tools volume`) should
+ * reject `not-found` explicitly — that's a malformed input, not a valid
+ * standard token. `fallback-network` is the degraded case where we couldn't
+ * reach the API but the token may still be valid; typically we default to
+ * `standard` and let Helper3 be the arbiter.
+ */
+import type { Address } from 'viem';
+import type { TokenVariant } from '../datastore/types.js';
+export type IdentifySource = 'api' | 'not-found' | 'fallback-network';
+export type IdentifyResult = {
+    variant: TokenVariant;
+    /** Where the verdict came from */
+    source: IdentifySource;
+    /** Optional raw API payload for debugging / downstream use */
+    raw?: FourmemeTokenResponse | undefined;
+};
+/** Shape of the Four.meme token/get API response (fields we care about) */
+export type FourmemeTokenResponse = {
+    code: number;
+    msg: string;
+    data: {
+        address: string;
+        name: string;
+        shortName: string;
+        symbol: string;
+        totalAmount: string;
+        saleAmount: string;
+        launchTime: number;
+        /** "V3" standard, "V8" X Mode exclusive */
+        version: string;
+        /** PANCAKE_SWAP | ... */
+        dexType: string;
+        /** Present only on AntiSniperFee tokens */
+        feePlan?: boolean;
+        /** Present only on TaxTokens */
+        taxInfo?: {
+            feeRate: number;
+            recipientRate: number;
+            burnRate: number;
+            divideRate: number;
+            liquidityRate: number;
+            recipientAddress: string;
+            minSharing: number;
+        };
+        /** Present only when created by an agent wallet */
+        aiCreator?: boolean;
+    } | null;
+};
+/**
+ * Identify a Four.meme token's variant.
+ *
+ * Never throws: on network or API errors this returns `{ variant: 'standard',
+ * source: 'fallback' }`. Callers that want a hard guard should wrap this in
+ * `assertSupportedToken` (see guards.ts) which re-checks `source` semantics.
+ */
+export declare function identifyToken(ca: Address, options?: {
+    timeoutMs?: number | undefined;
+    fetchImpl?: typeof fetch | undefined;
+    apiBaseUrl?: string | undefined;
+}): Promise<IdentifyResult>;
+//# sourceMappingURL=identify.d.ts.map

package/dist/lib/identify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identify.d.ts","sourceRoot":"","sources":["../../src/lib/identify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAEnC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAMzD,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,WAAW,GAAG,kBAAkB,CAAA;AAErE,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,EAAE,YAAY,CAAA;IACrB,kCAAkC;IAClC,MAAM,EAAE,cAAc,CAAA;IACtB,8DAA8D;IAC9D,GAAG,CAAC,EAAE,qBAAqB,GAAG,SAAS,CAAA;CACxC,CAAA;AAED,2EAA2E;AAC3E,MAAM,MAAM,qBAAqB,GAAG;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE;QACJ,OAAO,EAAE,MAAM,CAAA;QACf,IAAI,EAAE,MAAM,CAAA;QACZ,SAAS,EAAE,MAAM,CAAA;QACjB,MAAM,EAAE,MAAM,CAAA;QACd,WAAW,EAAE,MAAM,CAAA;QACnB,UAAU,EAAE,MAAM,CAAA;QAClB,UAAU,EAAE,MAAM,CAAA;QAClB,2CAA2C;QAC3C,OAAO,EAAE,MAAM,CAAA;QACf,yBAAyB;QACzB,OAAO,EAAE,MAAM,CAAA;QACf,2CAA2C;QAC3C,OAAO,CAAC,EAAE,OAAO,CAAA;QACjB,gCAAgC;QAChC,OAAO,CAAC,EAAE;YACR,OAAO,EAAE,MAAM,CAAA;YACf,aAAa,EAAE,MAAM,CAAA;YACrB,QAAQ,EAAE,MAAM,CAAA;YAChB,UAAU,EAAE,MAAM,CAAA;YAClB,aAAa,EAAE,MAAM,CAAA;YACrB,gBAAgB,EAAE,MAAM,CAAA;YACxB,UAAU,EAAE,MAAM,CAAA;SACnB,CAAA;QACD,mDAAmD;QACnD,SAAS,CAAC,EAAE,OAAO,CAAA;KACpB,GAAG,IAAI,CAAA;CACT,CAAA;AAYD;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,EAAE,EAAE,OAAO,EACX,OAAO,GAAE;IACP,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9B,SAAS,CAAC,EAAE,OAAO,KAAK,GAAG,SAAS,CAAA;IACpC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC3B,GACL,OAAO,CAAC,cAAc,CAAC,CAwBzB"}

package/dist/lib/identify.js

@@ -0,0 +1,88 @@
+/**
+ * Token variant identification.
+ *
+ * Four.meme has four variants: standard / anti-sniper-fee / tax-token / x-mode.
+ *
+ * We detect the variant via Four.meme's public REST API
+ * (`https://four.meme/meme-api/v1/private/token/get?address=...`). The endpoint
+ * is public despite its "/private/" path segment — it's a read API for token
+ * metadata and requires no auth.
+ *
+ * Why not on-chain? The documented method is to read
+ * `TokenManager2._tokenInfos[token].template` and check specific bits
+ * (creatorType == 5 → tax-token, bit 0x10000 → x-mode). But the full
+ * TokenInfo + TokenInfoEx1 struct layout isn't published, and reverse-
+ * engineering struct encoding is fragile. The REST API gives us the same
+ * signals with documented field names and typed JSON.
+ *
+ * Three response states (carried in `IdentifyResult.source`):
+ *
+ *   - `api`                → got a real classification from the API
+ *   - `not-found`          → API responded with code != 0 or data === null,
+ *                             meaning the token isn't on Four.meme at all
+ *   - `fallback-network`   → HTTP / timeout / connection error, couldn't tell
+ *
+ * Commands that need strict guarantees (`trade buy`, `tools volume`) should
+ * reject `not-found` explicitly — that's a malformed input, not a valid
+ * standard token. `fallback-network` is the degraded case where we couldn't
+ * reach the API but the token may still be valid; typically we default to
+ * `standard` and let Helper3 be the arbiter.
+ */
+import { loadConfig } from './config.js';
+// ============================================================
+// Constants
+// ============================================================
+const DEFAULT_TIMEOUT_MS = 8_000;
+// ============================================================
+// Public API
+// ============================================================
+/**
+ * Identify a Four.meme token's variant.
+ *
+ * Never throws: on network or API errors this returns `{ variant: 'standard',
+ * source: 'fallback' }`. Callers that want a hard guard should wrap this in
+ * `assertSupportedToken` (see guards.ts) which re-checks `source` semantics.
+ */
+export async function identifyToken(ca, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const fetchFn = options.fetchImpl ?? globalThis.fetch;
+    const apiBase = options.apiBaseUrl ?? loadConfig().fourmemeApiUrl;
+    const url = `${apiBase}/v1/private/token/get?address=${ca}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetchFn(url, { signal: controller.signal });
+        if (!res.ok) {
+            return { variant: 'standard', source: 'fallback-network' };
+        }
+        const json = (await res.json());
+        if (json.code !== 0 || !json.data) {
+            return { variant: 'standard', source: 'not-found', raw: json };
+        }
+        return { variant: classify(json.data), source: 'api', raw: json };
+    }
+    catch {
+        return { variant: 'standard', source: 'fallback-network' };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+// ============================================================
+// Classification rules
+// ============================================================
+function classify(data) {
+    // Priority:
+    //   1. tax-token (most specific)
+    //   2. x-mode (protocol-level exclusivity gate)
+    //   3. anti-sniper-fee (dynamic fee)
+    //   4. standard (default)
+    if (data.taxInfo)
+        return 'tax-token';
+    if (data.version === 'V8')
+        return 'x-mode';
+    if (data.feePlan === true)
+        return 'anti-sniper-fee';
+    return 'standard';
+}
+//# sourceMappingURL=identify.js.map

package/dist/lib/identify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identify.js","sourceRoot":"","sources":["../../src/lib/identify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAkDxC,+DAA+D;AAC/D,YAAY;AACZ,+DAA+D;AAE/D,MAAM,kBAAkB,GAAG,KAAK,CAAA;AAEhC,+DAA+D;AAC/D,aAAa;AACb,+DAA+D;AAE/D;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,EAAW,EACX,UAII,EAAE;IAEN,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,kBAAkB,CAAA;IACzD,MAAM,OAAO,GAAG,OAAO,CAAC,SAAS,IAAI,UAAU,CAAC,KAAK,CAAA;IACrD,MAAM,OAAO,GAAG,OAAO,CAAC,UAAU,IAAI,UAAU,EAAE,CAAC,cAAc,CAAA;IAEjE,MAAM,GAAG,GAAG,GAAG,OAAO,iCAAiC,EAAE,EAAE,CAAA;IAC3D,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAA;IACxC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAA;IAE7D,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC,CAAA;QAC7D,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAA;QAC5D,CAAC;QACD,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAA0B,CAAA;QACxD,IAAI,IAAI,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YAClC,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,IAAI,EAAE,CAAA;QAChE,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,CAAA;IACnE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAA;IAC5D,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,KAAK,CAAC,CAAA;IACrB,CAAC;AACH,CAAC;AAED,+DAA+D;AAC/D,uBAAuB;AACvB,+DAA+D;AAE/D,SAAS,QAAQ,CAAC,IAAgD;IAChE,YAAY;IACZ,iCAAiC;IACjC,gDAAgD;IAChD,qCAAqC;IACrC,0BAA0B;IAC1B,IAAI,IAAI,CAAC,OAAO;QAAE,OAAO,WAAW,CAAA;IACpC,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI;QAAE,OAAO,QAAQ,CAAA;IAC1C,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI;QAAE,OAAO,iBAAiB,CAAA;IACnD,OAAO,UAAU,CAAA;AACnB,CAAC"}