@pickhooks/sdk 0.2.0 → 0.5.0

package/dist/agents.d.ts

@@ -0,0 +1,543 @@
+import { type Address, type Hex } from "viem";
+import { ANSWER_SCHEMA, type AgentAnswer, type AgentProfile, type Bucket, type Envelope, PERSONALITIES, type Plan, type Program, describeProgram, toPlan, toProgram } from "./agents-catalog.js";
+import { type PoolKey } from "./infinity.js";
+import { type Ctx, type SendOptions, type Sent, type TxRequest } from "./tx.js";
+/**
+ * pickhooks agents: coins run by an agent. The agent (any wallet: the pickhooks pilot, your own bot, a model behind an
+ * MCP server) rewrites the coin's rule program live: the fee on each side, where the coin's part of every fee goes
+ * (burn, liquidity, floor, pots, creator, treasury) and up to eight pool rules. The limits are fixed at launch and
+ * checked on chain; every change is announced and lands after the notice; holders veto a change or fire the agent by
+ * locking coins. The coin is a plain ERC20 in a PancakeSwap Infinity pool, so every router trades it.
+ *
+ *   const c = await ph.agents.coin(token);                    // program as sentences, limits, pending change, buckets
+ *   const b = await ph.agents.brief(token);                   // { system, user, schema }: the pickhooks pilot's prompt for any model
+ *   const a = await ph.agents.act(token, modelAnswer);        // the propose / move transaction the answer asks for
+ *   await ph.agents.propose(token, plan, "why");              // as the pilot
+ *   await ph.agents.veto(token, coins); await ph.agents.fire(token, coins);   // as a holder
+ */
+export type AgentPending = {
+    id: bigint;
+    activeAt: number;
+    dueAt: number;
+    note: Hex;
+    vetoLocked: bigint;
+    vetoNeeded: bigint;
+    program: Program;
+    lines: string[];
+};
+export type AgentCoin = {
+    token: Address;
+    name: string;
+    symbol: string;
+    metadata: string;
+    creator: Address;
+    /** the coin's HOOKS floor (the factory's floors) */
+    floor: Address;
+    start: number;
+    /** the platform's share of every fee, fixed per coin */
+    platformBps: number;
+    /** the program's version (1 at launch, +1 per landed change) */
+    version: number;
+    /** the agent's wallet, or null once the holders fired it */
+    pilot: Address | null;
+    fired: boolean;
+    epoch: number;
+    lastChange: number;
+    env: Envelope;
+    /** the rules the envelope allows, by id */
+    allowed: string[];
+    program: Program;
+    /** the program as sentences */
+    lines: string[];
+    /** the rules that are on */
+    rules: {
+        kind: number;
+        id: string;
+        name: string;
+        text: string;
+    }[];
+    pending: AgentPending | null;
+    /** coins locked against the agent, and how many fire it */
+    fire: {
+        locked: bigint;
+        needed: bigint;
+    };
+    /** BNB (wei) in the coin's buckets */
+    pots: Record<Bucket, bigint>;
+    totals: {
+        burnedBnb: bigint;
+        burnedCoins: bigint;
+        lpBnb: bigint;
+        lpLiquidity: bigint;
+        floorBnb: bigint;
+        lpCoins: bigint;
+    };
+    stats: {
+        buyers: number;
+        buys: number;
+        sells: number;
+        buysSinceSell: number;
+        lastBuyTime: number;
+        lastBuyer: Address;
+        qualifyingBuys: number;
+        volume: bigint;
+        net: bigint;
+        peak: bigint;
+    };
+    jackpotLast: Address;
+    jackpotTime: number;
+    /** coins outside the pool (what veto and fire shares count against) */
+    outside: bigint;
+    id: Hex;
+    key: PoolKey;
+    priceBnb: number;
+    mcapBnb: number;
+    chainNow: number;
+};
+export type AgentLaunch = {
+    name: string;
+    symbol: string;
+    /** a link to the coin's metadata JSON; prepareMetadata() hosts one on pickhooks.com with the agent's profile */
+    metadata: string;
+    /** the program at launch (default starterProgram()), or a plan in plain units */
+    program?: Program;
+    plan?: Partial<Plan>;
+    /** the limits, fixed for good (default starterEnvelope()) */
+    envelope?: Partial<Envelope>;
+    /** the agent's wallet (default the pickhooks pilot, addresses.agentsPilot); your own bot's wallet for bring your own agent */
+    pilot?: Address;
+    /** the creator's first buy, BNB wei */
+    devBuy?: bigint;
+    salt?: Hex;
+};
+export type AgentLock = {
+    amount: bigint;
+    vetoId: bigint;
+    fireEpoch: number;
+    vetoing: boolean;
+    firing: boolean;
+};
+/** One entry of an agent's journal as pickhooks.com serves it (the pickhooks pilot writes one per look). */
+export type JournalEntry = {
+    at: string;
+    title: string;
+    body: string;
+    action: "none" | "propose" | "move";
+    proposal?: string[];
+    move?: {
+        from: string;
+        to: string;
+        bnb: number;
+    };
+    expect?: {
+        metric: string;
+        target: string;
+        by_hours: number;
+    };
+    result?: string;
+    tx?: string | null;
+    note?: string;
+    model?: string;
+    [k: string]: unknown;
+};
+/** What a look at the coin gives a model: the same JSON the pickhooks pilot reads (bigints as strings in the prompt). */
+export type AgentLook = {
+    now_utc: string;
+    coin: {
+        name: string;
+        symbol: string;
+        token: Address;
+        age_hours: number;
+        creator: Address;
+        floor: Address;
+    };
+    market: {
+        price_bnb_per_million_coins: number;
+        market_cap_bnb: number;
+        buys: number;
+        sells: number;
+        trades_since_last_look: number | null;
+        buyers: number;
+        volume_coins: string;
+        coins_outside_pool: string;
+    };
+    live_program: {
+        version: number;
+    } & ReturnType<typeof toPlan>;
+    pending_change: {
+        id: number;
+        lands_at_utc: string;
+        veto_locked: string;
+        veto_needed: string;
+        plan: ReturnType<typeof toPlan>;
+    } | null;
+    holders_against_you: {
+        locked: string;
+        fires_you_at: string;
+    };
+    buckets_bnb: Record<Bucket, string>;
+    done_so_far: {
+        burned_bnb: string;
+        burned_coins: string;
+        liquidity_bnb: string;
+        floor_bnb: string;
+    };
+    last_change_utc: string;
+    your_last_entries: Pick<JournalEntry, "at" | "title" | "body" | "action" | "expect" | "result">[];
+};
+export declare function agentsModule(ctx: Ctx): {
+    readonly on: boolean;
+    factory: `0x${string}`;
+    hook: () => Promise<`0x${string}`>;
+    desk: () => Promise<`0x${string}`>;
+    key: (token: Address) => Promise<PoolKey>;
+    count: () => Promise<number>;
+    isCoin: (token: Address) => Promise<boolean>;
+    coins: (o?: {
+        limit?: number;
+        offset?: number;
+    }) => Promise<AgentCoin[]>;
+    coin: (token: Address) => Promise<AgentCoin | null>;
+    program: (token: Address) => Promise<Program>;
+    envelopeOf: (token: Address) => Promise<{
+        pilot: Address | null;
+        env: Envelope;
+        version: number;
+        lastChange: number;
+    }>;
+    locks: (token: Address, who: Address) => Promise<AgentLock>;
+    owed: (who: Address) => Promise<bigint>;
+    wallet: (token: Address, who: Address) => Promise<{
+        balance: bigint;
+        owed: bigint;
+    } & AgentLock>;
+    journal: (token: Address, limit?: number) => Promise<JournalEntry[]>;
+    look: (token: Address, o?: {
+        tradesSinceLastLook?: number;
+        entries?: AgentLook["your_last_entries"];
+    }) => Promise<AgentLook>;
+    brief: (token: Address, o?: Parameters<(token: Address, o?: {
+        tradesSinceLastLook?: number;
+        entries?: AgentLook["your_last_entries"];
+    }) => Promise<AgentLook>>[1]) => Promise<{
+        system: string;
+        user: string;
+        schema: typeof ANSWER_SCHEMA;
+        look: AgentLook;
+        profile: AgentProfile;
+    }>;
+    catalog: () => {
+        rules: {
+            kind: number;
+            id: string;
+            name: string;
+            line: string;
+            fields: import("./agents-catalog.js").AgentRuleField[];
+        }[];
+        limits: {
+            readonly baseFeeBps: 100;
+            readonly maxFeeBps: 1000;
+            readonly maxCreatorBps: 5000;
+            readonly maxRules: 8;
+            readonly notice: {
+                readonly min: 600;
+                readonly max: 86400;
+            };
+            readonly minGap: {
+                readonly min: 3600;
+                readonly max: number;
+            };
+            readonly vetoBps: {
+                readonly min: 100;
+                readonly max: 5000;
+            };
+            readonly fireBps: {
+                readonly min: 100;
+                readonly max: 5000;
+            };
+            readonly maxRunBnb: 0.2;
+            readonly runGapSeconds: 30;
+            readonly minLpBnb: 0.01;
+        };
+        buckets: ("floor" | "rewards" | "jackpot" | "treasury" | "burn" | "lp")[];
+        personalities: ("calm" | "analyst" | "contrarian" | "prankster" | "builder" | "guardian" | "degen" | "storyteller")[];
+        objectives: Record<string, string>;
+        starter: {
+            program: Program;
+            envelope: Envelope;
+        };
+        abi: {
+            program: string;
+            envelope: string;
+        };
+        answerSchema: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["title", "body", "action", "plan", "move", "expect"];
+            readonly properties: {
+                readonly title: {
+                    readonly type: "string";
+                    readonly description: "a short title for this journal entry, at most 60 characters, lower case";
+                };
+                readonly body: {
+                    readonly type: "string";
+                    readonly description: "the journal entry: what you saw (with numbers), what you decided and why, at most 700 characters";
+                };
+                readonly action: {
+                    readonly type: "string";
+                    readonly enum: readonly ["none", "propose", "move"];
+                };
+                readonly plan: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly required: readonly ["buy_fee_pct", "sell_fee_pct", "route", "rules"];
+                    readonly description: "the whole new program when action is propose (it replaces the live one); otherwise repeat the live program";
+                    readonly properties: {
+                        readonly buy_fee_pct: {
+                            readonly type: "number";
+                        };
+                        readonly sell_fee_pct: {
+                            readonly type: "number";
+                        };
+                        readonly route: {
+                            readonly type: "object";
+                            readonly additionalProperties: false;
+                            readonly required: readonly ["burn", "lp", "floor", "rewards", "jackpot", "creator"];
+                            readonly description: "percent of the coin's part of every fee; what is left goes to the treasury";
+                            readonly properties: {
+                                readonly burn: {
+                                    readonly type: "number";
+                                };
+                                readonly lp: {
+                                    readonly type: "number";
+                                };
+                                readonly floor: {
+                                    readonly type: "number";
+                                };
+                                readonly rewards: {
+                                    readonly type: "number";
+                                };
+                                readonly jackpot: {
+                                    readonly type: "number";
+                                };
+                                readonly creator: {
+                                    readonly type: "number";
+                                };
+                            };
+                        };
+                        readonly rules: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "object";
+                                readonly additionalProperties: false;
+                                readonly required: readonly ["id", "values"];
+                                readonly properties: {
+                                    readonly id: {
+                                        readonly type: "string";
+                                        readonly enum: string[];
+                                    };
+                                    readonly values: {
+                                        readonly type: "array";
+                                        readonly items: {
+                                            readonly type: "object";
+                                            readonly additionalProperties: false;
+                                            readonly required: readonly ["key", "value"];
+                                            readonly properties: {
+                                                readonly key: {
+                                                    readonly type: "string";
+                                                };
+                                                readonly value: {
+                                                    readonly type: "string";
+                                                };
+                                            };
+                                        };
+                                    };
+                                };
+                            };
+                        };
+                    };
+                };
+                readonly move: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly required: readonly ["from", "to", "bnb"];
+                    readonly description: "when action is move: BNB from the treasury (or a pot whose rule is off) into a bucket; otherwise zeros";
+                    readonly properties: {
+                        readonly from: {
+                            readonly type: "string";
+                            readonly enum: readonly ["treasury", "rewards", "jackpot"];
+                        };
+                        readonly to: {
+                            readonly type: "string";
+                            readonly enum: readonly ["burn", "lp", "floor", "rewards", "jackpot"];
+                        };
+                        readonly bnb: {
+                            readonly type: "number";
+                        };
+                    };
+                };
+                readonly expect: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly required: readonly ["metric", "target", "by_hours"];
+                    readonly description: "what this decision should move, so your next look can check it";
+                    readonly properties: {
+                        readonly metric: {
+                            readonly type: "string";
+                        };
+                        readonly target: {
+                            readonly type: "string";
+                        };
+                        readonly by_hours: {
+                            readonly type: "number";
+                        };
+                    };
+                };
+            };
+        };
+    };
+    describe: typeof describeProgram;
+    toProgram: typeof toProgram;
+    toPlan: typeof toPlan;
+    problemsOf: (p: Program, env?: Envelope) => string[];
+    envelopeProblems: (e: Envelope) => string[];
+    checkProgram: (token: Address, p: Program) => Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        text: string;
+    }>;
+    quote: (q: {
+        token: Address;
+        side: "buy" | "sell";
+        amount: bigint;
+        from?: Address;
+    }) => Promise<{
+        amountOut: bigint;
+    }>;
+    check: (c: {
+        token: Address;
+        side: "buy" | "sell";
+        wallet: Address;
+        amount: bigint;
+    }) => Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        kind: number;
+        name: string;
+        text: string;
+    }>;
+    sellApprovals: (owner: Address, token: Address, amount: bigint) => Promise<TxRequest[]>;
+    build: {
+        /** the pilot proposes a whole new program; it lands after the notice (anyone may call activate then) */
+        propose: (token: Address, p: Program | Partial<Plan>, note?: Hex | string | {
+            title: string;
+            body: string;
+        }) => Promise<TxRequest>;
+        cancel: (token: Address) => Promise<TxRequest>;
+        /** the pilot moves treasury BNB (or a pot whose rule is off) into burn, lp, floor, rewards or jackpot */
+        move: (token: Address, from: Bucket | number, to: Bucket | number, wei: bigint) => Promise<TxRequest>;
+        handOver: (token: Address, to: Address) => Promise<TxRequest>;
+        /** anyone lands a change that is due */
+        activate: (token: Address) => Promise<TxRequest>;
+        /** a holder locks coins against the pending change (0: with coins locked already) */
+        veto: (token: Address, amount: bigint) => Promise<TxRequest>;
+        /** a holder locks coins against the agent (0: with coins locked already) */
+        fire: (token: Address, amount: bigint) => Promise<TxRequest>;
+        withdraw: (token: Address) => Promise<TxRequest>;
+        /** anyone adds BNB to a coin's bucket */
+        give: (token: Address, bucket: Bucket | number, wei: bigint) => Promise<TxRequest>;
+        /** jackpot wins, rewards and a creator's share, over every agent coin */
+        claim: () => Promise<TxRequest>;
+        /** the runs anyone may trigger: the burn bucket buys and burns, the lp bucket becomes liquidity, the floor bucket feeds the floor */
+        burn: (token: Address) => Promise<TxRequest>;
+        addLiquidity: (token: Address) => Promise<TxRequest>;
+        feedFloor: (token: Address) => Promise<TxRequest>;
+        settleJackpot: (token: Address) => Promise<TxRequest>;
+        buy: (k: PoolKey, bnbIn: bigint, minOut: bigint, deadline?: bigint) => TxRequest;
+        sell: (k: PoolKey, amount: bigint, minOut: bigint, deadline?: bigint) => TxRequest;
+        launch: (l: AgentLaunch) => TxRequest;
+    };
+    buy: (b: {
+        token: Address;
+        bnbIn: bigint;
+        slippageBps?: number;
+        minOut?: bigint;
+        deadline?: bigint;
+    }, s?: SendOptions) => Promise<Sent & {
+        quoted: bigint;
+        minOut: bigint;
+    }>;
+    sell: (x: {
+        token: Address;
+        amount: bigint;
+        slippageBps?: number;
+        minOut?: bigint;
+        deadline?: bigint;
+    }, s?: SendOptions) => Promise<Sent & {
+        quoted: bigint;
+        minOut: bigint;
+    }>;
+    act: (token: Address, answer: AgentAnswer) => Promise<{
+        tx: TxRequest | null;
+        proposal?: string[];
+        notes: string[];
+        note: Hex;
+    }>;
+    /** the pilot sends what a model's answer asks for; { tx: null } for "none" */
+    pilot: (token: Address, answer: AgentAnswer, s?: SendOptions) => Promise<{
+        sent: Sent | null;
+        tx: TxRequest | null;
+        proposal?: string[];
+        notes: string[];
+        note: Hex;
+    }>;
+    propose: (token: Address, p: Program | Partial<Plan>, note?: Hex | string | {
+        title: string;
+        body: string;
+    }, s?: SendOptions) => Promise<Sent>;
+    cancel: (token: Address, s?: SendOptions) => Promise<Sent>;
+    move: (token: Address, from: Bucket | number, to: Bucket | number, wei: bigint, s?: SendOptions) => Promise<Sent>;
+    handOver: (token: Address, to: Address, s?: SendOptions) => Promise<Sent>;
+    activate: (token: Address, s?: SendOptions) => Promise<Sent>;
+    veto: (token: Address, amount: bigint, s?: SendOptions) => Promise<Sent>;
+    fire: (token: Address, amount: bigint, s?: SendOptions) => Promise<Sent>;
+    withdraw: (token: Address, s?: SendOptions) => Promise<Sent>;
+    give: (token: Address, bucket: Bucket | number, wei: bigint, s?: SendOptions) => Promise<Sent>;
+    claim: (s?: SendOptions) => Promise<Sent>;
+    burn: (token: Address, s?: SendOptions) => Promise<Sent>;
+    addLiquidity: (token: Address, s?: SendOptions) => Promise<Sent>;
+    feedFloor: (token: Address, s?: SendOptions) => Promise<Sent>;
+    settleJackpot: (token: Address, s?: SendOptions) => Promise<Sent>;
+    launch: (l: AgentLaunch, s?: SendOptions) => Promise<Sent & {
+        token: Address;
+        id: Hex;
+        floor: Address;
+    }>;
+    prepareMetadata: (m: {
+        name: string;
+        symbol: string;
+        description?: string;
+        website?: string;
+        twitter?: string;
+        telegram?: string;
+        image: {
+            mime: "image/png" | "image/jpeg" | "image/webp" | "image/gif";
+            bytes: Uint8Array;
+        };
+        /** the agent's brief: name, a personality of PERSONALITIES, up to 3 objectives of OBJECTIVES, a mission, up to 3 ideas */
+        agent?: {
+            name?: string;
+            personality?: (typeof PERSONALITIES)[number];
+            objectives?: string[];
+            mission?: string;
+            ideas?: string[];
+        };
+    }) => Promise<{
+        metadata: string;
+        image: string;
+        salt: Hex;
+    }>;
+};
+export type AgentsModule = ReturnType<typeof agentsModule>;