@pickhooks/sdk 0.0.0-stage → 0.4.0

package/dist/agents-catalog.d.ts

@@ -0,0 +1,318 @@
+import { type Hex } from "viem";
+import { type R } from "./coin-rules.js";
+/**
+ * pickhooks agents: what an agent can write. A typed port of the site's web/src/lib/agents-catalog.mjs (the file the
+ * site, the keeper's pilot and the API share) plus the pilot's prompt and answer schema from web/keeper/pilot-step.mjs,
+ * so any model can run a coin the way the pickhooks agent does. `npm run check` keeps the port equal to the site's copy.
+ *
+ * A program (AgentsTypes.sol Program) = the pool rules an agent may use + the fee per side + where the coin's part of
+ * every fee goes. The chain checks every program again (AgentsLimits); this file only builds and explains them.
+ */
+/** The program of an agent coin, as the chain stores it (bps = basis points). */
+export type Program = {
+    /** the pool rules (only kinds of AGENT_RULES, at most 8 on) */
+    r: R;
+    buyFeeBps: number;
+    sellFeeBps: number;
+    /** basis points of the coin's part of every fee: burn, liquidity, floor, the two pots, the creator; the rest is treasury */
+    burnBps: number;
+    lpBps: number;
+    floorBps: number;
+    rewardsBps: number;
+    jackpotBps: number;
+    creatorBps: number;
+};
+/** The limits of an agent coin, fixed for good at launch. */
+export type Envelope = {
+    maxFeeBps: number;
+    maxCreatorBps: number;
+    allowedMask: bigint;
+    /** seconds a change is announced before it can land */
+    notice: number;
+    /** seconds between two changes landing */
+    minGap: number;
+    /** share (bps) of the coins outside the pool that, locked against a change, kills it */
+    vetoBps: number;
+    /** share (bps) of the coins outside the pool that, locked against the agent, fires it */
+    fireBps: number;
+};
+/** A program in plain units, the way a model writes it. */
+export type Plan = {
+    buy_fee_pct: number;
+    sell_fee_pct: number;
+    /** percent of the coin's part of every fee; what is left goes to the treasury */
+    route: {
+        burn?: number;
+        lp?: number;
+        floor?: number;
+        rewards?: number;
+        jackpot?: number;
+        creator?: number;
+    };
+    rules: {
+        id: string;
+        values?: Record<string, number | string>;
+    }[];
+};
+export type AgentRuleField = {
+    key: string;
+    unit: string;
+    min?: number;
+    max?: number;
+    def: number | string;
+};
+export type AgentRule = {
+    /** the rule's bit in Rules.mask */
+    kind: number;
+    id: string;
+    name: string;
+    line: string;
+    fields: AgentRuleField[];
+    apply: (v: Record<string, number | string>) => Partial<R>;
+    describe: (r: R) => string;
+};
+export declare const PROGRAM_TUPLE = "((uint64 mask, uint16 maxWalletBps, uint16 riseStartBps, uint16 riseStepBps, uint32 riseSeconds, uint16 chapterStartBps, uint128 chapterVolume, uint32 clubMax, address gateToken, uint128 gateMin, uint16 maxTradeBps, uint16 buysPerBlock, uint64 maxGasPrice, uint16 raiseBps, uint32 raiseReset, uint128 minBuy, uint32 slowSeconds, uint16 buyLimit, uint16 dumpBuyBps, uint16 dumpSellBps, uint16 curveSmallBps, uint16 curveFloorBps, uint16 curveBigBagBps, uint16 taperStartBps, uint16 taperEndBps, uint16 taperSoldBps, uint16 unlockBuys, uint32 devLockSeconds, uint16 devCapBps, uint32 devGapSeconds, uint32 diamondSeconds, uint32 cooldownSeconds, uint32 jailWindow, uint32 jailSeconds, uint8 openHour, uint8 closeHour, uint8 weekdays, bool sellsOpen, uint32 sellWindow, uint32 sellPeriod, uint32 tickSeconds, uint32 bellSeconds, uint16 bellSoldBps, uint128 rewardPerBuy, uint128 rewardMinBuy, uint16 rewardEveryN, uint32 jackpotSilence, uint16 jackpotShareBps, uint128 jackpotMinBuy, uint16 jackpotFeeBps, uint16 dipBps, address beacon, uint16 beaconTargetBps, address partner, uint16 reactBaseBps, uint16 reactSensitivity) r, uint16 buyFeeBps, uint16 sellFeeBps, uint16 burnBps, uint16 lpBps, uint16 floorBps, uint16 rewardsBps, uint16 jackpotBps, uint16 creatorBps)";
+export declare const ENVELOPE_TUPLE = "(uint16 maxFeeBps, uint16 maxCreatorBps, uint64 allowedMask, uint32 notice, uint32 minGap, uint16 vetoBps, uint16 fireBps)";
+export declare const decodeProgram: (bytes: Hex) => Program;
+export declare const encodeProgram: (p: Program) => Hex;
+/** The BNB buckets of an agent coin in the hook, by index (treasury 0 … jackpot 5). */
+export declare const BUCKETS: readonly ["treasury", "burn", "lp", "floor", "rewards", "jackpot"];
+export type Bucket = (typeof BUCKETS)[number];
+export declare const SUPPLY = 1000000000;
+/** The pool rules an agent may use (AgentsLimits.KNOWN). kind = the rule's bit, fields in the units the model writes. */
+export declare const AGENT_RULES: AgentRule[];
+export declare const AGENT_RULE_BY_ID: Map<string, AgentRule>;
+export declare const AGENT_RULE_BY_KIND: Map<number, AgentRule>;
+/** every rule an agent may switch on, as a mask (the widest allowedMask a coin can have) */
+export declare const ALLOWED_MASK: bigint;
+/** The numbers AgentsLimits checks on chain (the chain is the truth; these mirror it). */
+export declare const AGENT_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;
+    };
+    /** a run (burn, liquidity) spends at most this much BNB at once, and runs are at least this many seconds apart */
+    readonly maxRunBnb: 0.2;
+    readonly runGapSeconds: 30;
+    /** the liquidity bucket runs from this much BNB */
+    readonly minLpBnb: 0.01;
+};
+/**
+ * A plan in plain units -> a Program for the chain. Unknown rules are dropped (named in `notes`), numbers are clamped
+ * into each field's range; the chain checks everything again.
+ */
+export declare function toProgram(plan: Partial<Plan>): {
+    program: Program;
+    notes: string[];
+};
+/** A program as sentences: the fees, where the coin's part goes, and every rule. */
+export declare function describeProgram(p: Program): string[];
+/** A program back into the plan a model writes (its memory of what is live), with the sentences. */
+export declare function toPlan(p: Program): Plan & {
+    sentences: string[];
+};
+/** The rules of a program by kind (the ones that are on). */
+export declare const agentKindsOf: (mask: bigint | number) => number[];
+/** The default program of a new agent coin: 1 % each side, half the coin's part burns, a quarter deepens the pool. */
+export declare function starterProgram(): Program;
+/** The default limits of a new agent coin. */
+export declare function starterEnvelope(): Envelope;
+export declare const PERSONALITIES: readonly ["calm", "analyst", "contrarian", "prankster", "builder", "guardian", "degen", "storyteller"];
+export declare const OBJECTIVES: Record<string, string>;
+/** The profile a creator wrote for the agent (the `agent` object of the coin's metadata JSON). A brief, never orders. */
+export type AgentProfile = {
+    symbol: string;
+    name?: string;
+    description?: string;
+    agentName?: string;
+    personality?: string;
+    objectives?: string[];
+    mission?: string;
+    ideas?: string[];
+};
+/** What a model answers per look: one journal entry and at most one action (the schema the pickhooks pilot uses, strict JSON). */
+export type AgentAnswer = {
+    title: string;
+    body: string;
+    action: "none" | "propose" | "move";
+    plan: {
+        buy_fee_pct: number;
+        sell_fee_pct: number;
+        route: Record<string, number>;
+        rules: {
+            id: string;
+            values: {
+                key: string;
+                value: string;
+            }[];
+        }[];
+    };
+    move: {
+        from: "treasury" | "rewards" | "jackpot";
+        to: "burn" | "lp" | "floor" | "rewards" | "jackpot";
+        bnb: number;
+    };
+    expect: {
+        metric: string;
+        target: string;
+        by_hours: number;
+    };
+};
+/** The answer schema: strict JSON, every property required (OpenAI / OpenRouter strict mode, Anthropic output formats). */
+export declare const ANSWER_SCHEMA: {
+    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";
+                };
+            };
+        };
+    };
+};
+/** The system prompt the pickhooks pilot runs with: the coin's character and objective, how fees route, the rules, the limits, the answer. */
+export declare function systemPrompt(profile: AgentProfile, env: Pick<Envelope, "maxFeeBps" | "maxCreatorBps" | "notice" | "minGap" | "vetoBps" | "fireBps">, platformPct: number): string;
+/** The user message of a look: the coin's state as JSON (bigints as strings) and the ask. */
+export declare function userPrompt(ctx: unknown): string;
+/** A model's plan (values as strings) -> the plan toProgram reads (numbers where they are numbers). */
+export declare function readPlan(plan: AgentAnswer["plan"]): Plan;
+/** The note a change carries on chain: keccak256 of "title\nbody", so the change and its reason match (the pickhooks pilot's convention). */
+export declare function noteHash(entry: {
+    title: string;
+    body: string;
+}): Hex;
+/**
+ * A model's answer text as JSON. A model that writes a line break inside a string (a journal body with paragraphs)
+ * breaks JSON.parse ("Unterminated string"): control characters inside strings are escaped first, then parsed again.
+ */
+export declare function parseAnswer(content: string): AgentAnswer;