@ripplesdotrun/agent-sdk 0.1.0 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ripples
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -11,13 +11,17 @@ mint and nobody, including the person who created it, can raise those limits aft
 npm install @ripplesdotrun/agent-sdk viem
 ```
 
+ESM only, Node 20 or newer.
+
 ## Launch one
 
 ```ts
 import { privateKeyToAccount } from "viem/accounts";
 import { createRipplesAgent } from "@ripplesdotrun/agent-sdk";
 
-const agent = createRipplesAgent({ account: privateKeyToAccount(process.env.KEY) });
+const agent = createRipplesAgent({
+  account: privateKeyToAccount(process.env.KEY as `0x${string}`),
+});
 
 const { treasury, token, market, collection } = await agent.launch({
   runway: "0.05",
@@ -55,7 +59,7 @@ await agent.claim();             // the trade fees and the collection's share of
 
 await agent.charter();   // the limits, which never change
 await agent.budget();    // what is left of today's, on the UTC day
-await agent.activity();  // everything it has done, newest first
+await agent.activity();  // what it has done, newest first, over a block range
 ```
 
 ## The charter

package/dist/abi.d.ts

@@ -291,6 +291,62 @@ export declare const AGENT_FACTORY_ABI: readonly [{
     readonly name: "ZeroAddress";
     readonly type: "error";
     readonly inputs: readonly [];
+}, {
+    readonly name: "EmptyURI";
+    readonly type: "error";
+    readonly inputs: readonly [];
+}, {
+    readonly name: "InvalidAllocation";
+    readonly type: "error";
+    readonly inputs: readonly [];
+}, {
+    readonly name: "InvalidLockWindow";
+    readonly type: "error";
+    readonly inputs: readonly [];
+}, {
+    readonly name: "InvalidTokenIdentity";
+    readonly type: "error";
+    readonly inputs: readonly [];
+}, {
+    readonly name: "InvalidVesting";
+    readonly type: "error";
+    readonly inputs: readonly [];
+}, {
+    readonly name: "InvalidWindow";
+    readonly type: "error";
+    readonly inputs: readonly [];
+}, {
+    readonly name: "PriceOutOfRange";
+    readonly type: "error";
+    readonly inputs: readonly [];
+}, {
+    readonly name: "QuoteEconomicsMismatch";
+    readonly type: "error";
+    readonly inputs: readonly [];
+}, {
+    readonly name: "QuoteMismatch";
+    readonly type: "error";
+    readonly inputs: readonly [];
+}, {
+    readonly name: "QuoteNotApproved";
+    readonly type: "error";
+    readonly inputs: readonly [];
+}, {
+    readonly name: "RoyaltyTooHigh";
+    readonly type: "error";
+    readonly inputs: readonly [];
+}, {
+    readonly name: "SeedPriceOutOfBand";
+    readonly type: "error";
+    readonly inputs: readonly [];
+}, {
+    readonly name: "SeedSupplyTooThin";
+    readonly type: "error";
+    readonly inputs: readonly [];
+}, {
+    readonly name: "ZeroSupply";
+    readonly type: "error";
+    readonly inputs: readonly [];
 }];
 export declare const AGENT_TREASURY_ABI: readonly [{
     readonly name: "buy";
@@ -454,38 +510,6 @@ export declare const AGENT_TREASURY_ABI: readonly [{
         readonly type: "uint256";
         readonly name: "mintable";
     }];
-}, {
-    readonly name: "payees";
-    readonly type: "function";
-    readonly stateMutability: "view";
-    readonly inputs: readonly [];
-    readonly outputs: readonly [{
-        readonly type: "address[]";
-    }];
-}, {
-    readonly name: "CREATOR";
-    readonly type: "function";
-    readonly stateMutability: "view";
-    readonly inputs: readonly [];
-    readonly outputs: readonly [{
-        readonly type: "address";
-    }];
-}, {
-    readonly name: "OPERATOR";
-    readonly type: "function";
-    readonly stateMutability: "view";
-    readonly inputs: readonly [];
-    readonly outputs: readonly [{
-        readonly type: "address";
-    }];
-}, {
-    readonly name: "QUOTE";
-    readonly type: "function";
-    readonly stateMutability: "view";
-    readonly inputs: readonly [];
-    readonly outputs: readonly [{
-        readonly type: "address";
-    }];
 }, {
     readonly name: "token";
     readonly type: "function";
@@ -688,6 +712,56 @@ export declare const AGENT_TREASURY_ABI: readonly [{
     readonly name: "ZeroAmount";
     readonly type: "error";
     readonly inputs: readonly [];
+}, {
+    readonly name: "CurveEndReached";
+    readonly type: "error";
+    readonly inputs: readonly [];
+}, {
+    readonly name: "Expired";
+    readonly type: "error";
+    readonly inputs: readonly [];
+}, {
+    readonly name: "NativeInputUnsupported";
+    readonly type: "error";
+    readonly inputs: readonly [];
+}, {
+    readonly name: "NotOurPool";
+    readonly type: "error";
+    readonly inputs: readonly [];
+}, {
+    readonly name: "NotTradable";
+    readonly type: "error";
+    readonly inputs: readonly [];
+}, {
+    readonly name: "SlippageExceeded";
+    readonly type: "error";
+    readonly inputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "amountOut";
+    }, {
+        readonly type: "uint256";
+        readonly name: "minAmountOut";
+    }];
+}, {
+    readonly name: "Ended";
+    readonly type: "error";
+    readonly inputs: readonly [];
+}, {
+    readonly name: "InvalidQuantity";
+    readonly type: "error";
+    readonly inputs: readonly [];
+}, {
+    readonly name: "NotStarted";
+    readonly type: "error";
+    readonly inputs: readonly [];
+}, {
+    readonly name: "SupplyExceeded";
+    readonly type: "error";
+    readonly inputs: readonly [];
+}, {
+    readonly name: "WalletCapExceeded";
+    readonly type: "error";
+    readonly inputs: readonly [];
 }];
 export declare const ERC20_ABI: readonly [{
     readonly name: "approve";
@@ -728,22 +802,6 @@ export declare const ERC20_ABI: readonly [{
     readonly outputs: readonly [{
         readonly type: "uint256";
     }];
-}, {
-    readonly name: "decimals";
-    readonly type: "function";
-    readonly stateMutability: "view";
-    readonly inputs: readonly [];
-    readonly outputs: readonly [{
-        readonly type: "uint8";
-    }];
-}, {
-    readonly name: "symbol";
-    readonly type: "function";
-    readonly stateMutability: "view";
-    readonly inputs: readonly [];
-    readonly outputs: readonly [{
-        readonly type: "string";
-    }];
 }];
 export declare const LAUNCH_FACTORY_ABI: readonly [{
     readonly name: "launchFee";

package/dist/abi.js

@@ -20,6 +20,22 @@ export const AGENT_FACTORY_ABI = parseAbi([
     "error TooManyPayees()",
     "error WrongPayment()",
     "error ZeroAddress()",
+    // A launch is validated by the launch factory and the collection, and it is their reverts a
+    // caller actually meets. Without them here a refused launch decodes to a hex blob.
+    "error EmptyURI()",
+    "error InvalidAllocation()",
+    "error InvalidLockWindow()",
+    "error InvalidTokenIdentity()",
+    "error InvalidVesting()",
+    "error InvalidWindow()",
+    "error PriceOutOfRange()",
+    "error QuoteEconomicsMismatch()",
+    "error QuoteMismatch()",
+    "error QuoteNotApproved()",
+    "error RoyaltyTooHigh()",
+    "error SeedPriceOutOfBand()",
+    "error SeedSupplyTooThin()",
+    "error ZeroSupply()",
 ]);
 export const AGENT_TREASURY_ABI = parseAbi([
     "function buy(uint256 amountIn,uint256 minAmountOut,uint256 deadline) returns (uint256 spent,uint256 received)",
@@ -34,10 +50,6 @@ export const AGENT_TREASURY_ABI = parseAbi([
     "function freezeCollectionMetadata()",
     "function charter() view returns (address operator,uint128 dailySpend,uint128 perCallSpend,uint128 dailySell,uint32 dailyMint,address[] payees)",
     "function remainingToday() view returns (uint256 spend,uint256 sellable,uint256 mintable)",
-    "function payees() view returns (address[])",
-    "function CREATOR() view returns (address)",
-    "function OPERATOR() view returns (address)",
-    "function QUOTE() view returns (address)",
     "function token() view returns (address)",
     "function locker() view returns (address)",
     "function collection() view returns (address)",
@@ -64,12 +76,23 @@ export const AGENT_TREASURY_ABI = parseAbi([
     "error QuoteMismatch()",
     "error UnexpectedBalance()",
     "error ZeroAmount()",
+    // A trade reverts inside the router and a mint inside the collection, so their errors decode
+    // here or not at all. A missed floor is the likeliest failure an agent will ever hit.
+    "error CurveEndReached()",
+    "error Expired()",
+    "error NativeInputUnsupported()",
+    "error NotOurPool()",
+    "error NotTradable()",
+    "error SlippageExceeded(uint256 amountOut,uint256 minAmountOut)",
+    "error Ended()",
+    "error InvalidQuantity()",
+    "error NotStarted()",
+    "error SupplyExceeded()",
+    "error WalletCapExceeded()",
 ]);
 export const ERC20_ABI = parseAbi([
     "function approve(address spender,uint256 value) returns (bool)",
     "function allowance(address owner,address spender) view returns (uint256)",
     "function balanceOf(address account) view returns (uint256)",
-    "function decimals() view returns (uint8)",
-    "function symbol() view returns (string)",
 ]);
 export const LAUNCH_FACTORY_ABI = parseAbi(["function launchFee() view returns (uint256)"]);

package/dist/agent.d.ts

@@ -1,4 +1,4 @@
-import { type Account, type Address, type Hash, type Transport } from "viem";
+import { type Account, type Address, type Hash, type PublicClient, type Transport } from "viem";
 import { type RipplesDeployment, type RipplesNetwork } from "./chains.js";
 import { LINKED_DEFAULTS } from "./defaults.js";
 /**
@@ -92,6 +92,10 @@ export type RipplesAgentOptions = {
     /** Overrides the network's public endpoint. */
     rpcUrl?: string;
     transport?: Transport;
+    /** Share a reader with the host application rather than opening a second one. */
+    publicClient?: PublicClient;
+    /** Blocks to wait before a write is treated as landed. One by default. */
+    confirmations?: number;
     /** An existing treasury to work. `launch` fills this in when it creates one. */
     treasury?: Address;
 };
@@ -104,6 +108,8 @@ export type AgentClient = ReturnType<typeof createRipplesAgent>;
 export declare function createRipplesAgent(options?: RipplesAgentOptions): {
     network: RipplesNetwork;
     deployment: RipplesDeployment;
+    /** The wallet this client signs with, where it has one. */
+    readonly address: Address | undefined;
     readonly treasury: Address | undefined;
     /**
      * Create the agent, its market and its collection, in one transaction.
@@ -117,12 +123,12 @@ export declare function createRipplesAgent(options?: RipplesAgentOptions): {
     /** Buy the agent's own token on its own market, into the treasury. */
     buy(amount: string, options?: {
         minReceived?: string;
-        deadline?: number;
+        deadlineSeconds?: number;
     }): Promise<`0x${string}`>;
     /** Sell it back, against the charter's daily ceiling. Refused outright when that is zero. */
     sell(amount: string, options?: {
         minReceived?: string;
-        deadline?: number;
+        deadlineSeconds?: number;
     }): Promise<`0x${string}`>;
     /** Mint from its own collection. The pieces stay with the treasury. */
     mint(quantity: number, options?: {
@@ -140,8 +146,26 @@ export declare function createRipplesAgent(options?: RipplesAgentOptions): {
     charter(): Promise<AgentCharter>;
     /** What is left of each ceiling today. The window is the UTC day. */
     budget(): Promise<Budget>;
-    /** Everything the agent has done, newest first. */
-    activity(limit?: number): Promise<readonly Activity[]>;
+    /**
+     * Everything the agent has done, newest first.
+     *
+     * Providers cap how many blocks one `eth_getLogs` may span, and Robinhood Chain is past
+     * fifty million, so a range is asked for rather than assumed. `fromBlock` defaults to the
+     * last 50,000 blocks; pass the launch's own block for the whole history.
+     */
+    activity(options?: {
+        limit?: number;
+        fromBlock?: bigint;
+        toBlock?: bigint | "latest";
+    }): Promise<readonly Activity[]>;
+    /**
+     * Point the collection at its artwork, and close it.
+     *
+     * The treasury owns the collection, so these are the creator's only way to attach or repair
+     * a base URI after the launch. `freezeCollectionMetadata` is one-way.
+     */
+    setCollectionBaseUri(uri: string): Promise<`0x${string}`>;
+    freezeCollectionMetadata(): Promise<`0x${string}`>;
     /** The launch this treasury opened. */
     launched(): Promise<{
         token: `0x${string}`;
@@ -151,7 +175,7 @@ export declare function createRipplesAgent(options?: RipplesAgentOptions): {
     }>;
 };
 /** Whether this chain's factory deployed `treasury`, which is what makes its charter worth reading. */
-export declare function readAgent(treasury: Address, options?: {
+export declare function isRipplesAgent(treasury: Address, options?: {
     network?: RipplesNetwork;
     rpcUrl?: string;
 }): Promise<boolean>;

package/dist/agent.js

@@ -1,4 +1,4 @@
-import { createPublicClient, createWalletClient, formatUnits, http, keccak256, parseUnits, toHex, } from "viem";
+import { createPublicClient, createWalletClient, formatUnits, http, keccak256, parseEventLogs, parseUnits, toHex, } from "viem";
 import { AGENT_FACTORY_ABI, AGENT_TREASURY_ABI, ERC20_ABI, LAUNCH_FACTORY_ABI } from "./abi.js";
 import { chainOf, DEPLOYMENTS } from "./chains.js";
 import { LINKED_DEFAULTS, LINKED_RESERVES, MAX_PAYEES, PREGEN } from "./defaults.js";
@@ -15,7 +15,7 @@ export function createRipplesAgent(options = {}) {
     const record = DEPLOYMENTS[network];
     const chain = chainOf(network);
     const transport = options.transport ?? http(options.rpcUrl ?? record.rpcUrl);
-    const publicClient = createPublicClient({ chain, transport });
+    const publicClient = options.publicClient ?? createPublicClient({ chain, transport });
     const wallet = options.account
         ? createWalletClient({ account: options.account, chain, transport })
         : undefined;
@@ -39,15 +39,45 @@ export function createRipplesAgent(options = {}) {
     async function send(request) {
         const { wallet } = signer();
         const hash = await wallet.writeContract(request);
-        const receipt = await publicClient.waitForTransactionReceipt({ hash });
+        let receipt;
+        try {
+            receipt = await publicClient.waitForTransactionReceipt({
+                hash,
+                ...(options.confirmations === undefined ? {} : { confirmations: options.confirmations }),
+            });
+        }
+        catch (cause) {
+            // The transaction is in flight and the caller has nothing to name it by unless the hash
+            // comes out with the failure. Losing it after a launch means losing the treasury.
+            throw new RipplesAgentError(`Sent ${hash} and stopped waiting for it. It may still land: ${record.explorer}/tx/${hash}`, { cause });
+        }
         if (receipt.status !== "success") {
-            throw new RipplesAgentError(`The transaction reverted. ${record.explorer}/tx/${hash}`);
+            // The estimate passed and the state moved before inclusion, which for a trade means the
+            // floor was missed. Replaying the call at that block is what turns the receipt into a
+            // named error rather than a link.
+            // Replayed at the block it failed in, which is what turns the receipt into a named error.
+            // viem decodes the revert against the same ABI, so a missed floor reads as
+            // `SlippageExceeded(amountOut, minAmountOut)` rather than as a link to a block explorer.
+            let cause;
+            try {
+                const replay = { ...request, blockNumber: receipt.blockNumber };
+                await publicClient.simulateContract(replay);
+            }
+            catch (reason) {
+                cause = reason;
+            }
+            throw new RipplesAgentError(`The transaction reverted. ${record.explorer}/tx/${hash}`, cause ? { cause } : undefined);
         }
-        return hash;
+        return receipt;
     }
+    const sent = async (request) => (await send(request)).transactionHash;
     return {
         network,
         deployment: record,
+        /** The wallet this client signs with, where it has one. */
+        get address() {
+            return options.account?.address;
+        },
         get treasury() {
             return treasury;
         },
@@ -61,6 +91,11 @@ export function createRipplesAgent(options = {}) {
          */
         async launch(plan) {
             const { account } = signer();
+            // Everything the plan can get wrong is checked first, before a single read and long before
+            // the approve. An approve is a real transaction, and a launch refused after it leaves a
+            // creator out of pocket with nothing created.
+            const charter = chartered(plan.charter, quote, token);
+            planned(plan, charter, quote);
             const runway = quote(plan.runway);
             const fee = await publicClient.readContract({
                 address: record.tokenLaunchFactory,
@@ -70,7 +105,6 @@ export function createRipplesAgent(options = {}) {
             if (runway < fee) {
                 throw new RipplesAgentError(`The runway has to cover the ${showQuote(fee)} ${record.quoteSymbol} launch fee.`);
             }
-            const charter = chartered(plan.charter, quote, token);
             const balance = await publicClient.readContract({
                 address: record.quote,
                 abi: ERC20_ABI,
@@ -87,7 +121,7 @@ export function createRipplesAgent(options = {}) {
                 args: [account.address, record.agentTreasuryFactory],
             });
             if (allowance < runway) {
-                await send({
+                await sent({
                     address: record.quote,
                     abi: ERC20_ABI,
                     functionName: "approve",
@@ -143,30 +177,48 @@ export function createRipplesAgent(options = {}) {
                 account,
                 chain,
             };
-            const { result } = await publicClient.simulateContract(request);
-            const transaction = await send(request);
-            const [created, launchToken, market, collection, vesting] = result;
-            treasury = created;
+            // Simulated as a pre-flight only. Its return values are addresses `CREATE` will produce
+            // at the factory's current nonce, and any other launch landing first moves every one of
+            // them, so what was actually deployed is read out of the receipt instead.
+            await publicClient.simulateContract(request);
+            const receipt = await send(request);
+            const [created] = parseEventLogs({
+                abi: AGENT_FACTORY_ABI,
+                eventName: "AgentTreasuryCreated",
+                logs: receipt.logs,
+            });
+            if (!created) {
+                throw new RipplesAgentError(`The launch confirmed and its record could not be read. ${record.explorer}/tx/${receipt.transactionHash}`);
+            }
+            const [opened] = parseEventLogs({
+                abi: AGENT_TREASURY_ABI,
+                eventName: "Launched",
+                logs: receipt.logs.filter((log) => isSame(log.address, created.args.treasury)),
+            });
+            if (!opened) {
+                throw new RipplesAgentError(`The agent was created and its launch could not be read. ${record.explorer}/tx/${receipt.transactionHash}`);
+            }
+            treasury = created.args.treasury;
             return {
-                treasury: created,
-                token: launchToken,
-                market: market,
-                collection: collection,
-                vesting: vesting,
-                transaction,
+                treasury: created.args.treasury,
+                token: opened.args.token,
+                market: opened.args.locker,
+                collection: opened.args.collection,
+                vesting: opened.args.vesting,
+                transaction: receipt.transactionHash,
             };
         },
         /** Buy the agent's own token on its own market, into the treasury. */
         async buy(amount, options = {}) {
             const { account } = signer();
-            return send({
+            return sent({
                 address: held(),
                 abi: AGENT_TREASURY_ABI,
                 functionName: "buy",
                 args: [
                     quote(amount),
                     options.minReceived ? token(options.minReceived) : 0n,
-                    BigInt(options.deadline ?? Math.floor(Date.now() / 1000) + 300),
+                    deadline(options.deadlineSeconds),
                 ],
                 account,
                 chain,
@@ -175,14 +227,14 @@ export function createRipplesAgent(options = {}) {
         /** Sell it back, against the charter's daily ceiling. Refused outright when that is zero. */
         async sell(amount, options = {}) {
             const { account } = signer();
-            return send({
+            return sent({
                 address: held(),
                 abi: AGENT_TREASURY_ABI,
                 functionName: "sell",
                 args: [
                     token(amount),
                     options.minReceived ? quote(options.minReceived) : 0n,
-                    BigInt(options.deadline ?? Math.floor(Date.now() / 1000) + 300),
+                    deadline(options.deadlineSeconds),
                 ],
                 account,
                 chain,
@@ -191,7 +243,10 @@ export function createRipplesAgent(options = {}) {
         /** Mint from its own collection. The pieces stay with the treasury. */
         async mint(quantity, options = {}) {
             const { account } = signer();
-            return send({
+            if (!Number.isInteger(quantity) || quantity < 1 || quantity > MAX_MINT_PER_TX) {
+                throw new RipplesAgentError(`A mint is 1 to ${MAX_MINT_PER_TX} pieces in one transaction.`);
+            }
+            return sent({
                 address: held(),
                 abi: AGENT_TREASURY_ABI,
                 functionName: "mint",
@@ -203,7 +258,7 @@ export function createRipplesAgent(options = {}) {
         /** Pay one of the charter's published addresses. */
         async pay(to, amount) {
             const { account } = signer();
-            return send({
+            return sent({
                 address: held(),
                 abi: AGENT_TREASURY_ABI,
                 functionName: "pay",
@@ -215,7 +270,7 @@ export function createRipplesAgent(options = {}) {
         /** Write an entry in the agent's public run log. */
         async note(text, uri = "") {
             const { account } = signer();
-            return send({
+            return sent({
                 address: held(),
                 abi: AGENT_TREASURY_ABI,
                 functionName: "note",
@@ -227,7 +282,7 @@ export function createRipplesAgent(options = {}) {
         /** Take in the creator's share of every trade and the collection's share of every mint. */
         async claim() {
             const { account } = signer();
-            return send({
+            return sent({
                 address: held(),
                 abi: AGENT_TREASURY_ABI,
                 functionName: "claimFees",
@@ -239,7 +294,7 @@ export function createRipplesAgent(options = {}) {
         /** Take in the token slice the agent's own mints earned it, once the market has graduated. */
         async claimVested() {
             const { account } = signer();
-            return send({
+            return sent({
                 address: held(),
                 abi: AGENT_TREASURY_ABI,
                 functionName: "claimVested",
@@ -273,9 +328,63 @@ export function createRipplesAgent(options = {}) {
             });
             return { spend: showQuote(spend), sellable: showToken(sellable), mintable: Number(mintable) };
         },
-        /** Everything the agent has done, newest first. */
-        async activity(limit = 50) {
-            return readActivity(publicClient, held(), { limit, showQuote, showToken });
+        /**
+         * Everything the agent has done, newest first.
+         *
+         * Providers cap how many blocks one `eth_getLogs` may span, and Robinhood Chain is past
+         * fifty million, so a range is asked for rather than assumed. `fromBlock` defaults to the
+         * last 50,000 blocks; pass the launch's own block for the whole history.
+         */
+        async activity(options = {}) {
+            const toBlock = options.toBlock ?? "latest";
+            let fromBlock;
+            if (options.fromBlock === undefined) {
+                const head = await publicClient.getBlockNumber();
+                fromBlock = head > DEFAULT_LOG_SPAN ? head - DEFAULT_LOG_SPAN : 0n;
+            }
+            else {
+                fromBlock = options.fromBlock;
+            }
+            return readActivity(publicClient, held(), {
+                limit: options.limit ?? 50,
+                fromBlock,
+                toBlock,
+                quoteSymbol: record.quoteSymbol,
+                tokenSymbol: "tokens",
+                showQuote,
+                showToken,
+            });
+        },
+        /**
+         * Point the collection at its artwork, and close it.
+         *
+         * The treasury owns the collection, so these are the creator's only way to attach or repair
+         * a base URI after the launch. `freezeCollectionMetadata` is one-way.
+         */
+        async setCollectionBaseUri(uri) {
+            const { account } = signer();
+            if (!uri.endsWith("/")) {
+                throw new RipplesAgentError("A base URI has to end in a slash.");
+            }
+            return sent({
+                address: held(),
+                abi: AGENT_TREASURY_ABI,
+                functionName: "setCollectionBaseURI",
+                args: [uri],
+                account,
+                chain,
+            });
+        },
+        async freezeCollectionMetadata() {
+            const { account } = signer();
+            return sent({
+                address: held(),
+                abi: AGENT_TREASURY_ABI,
+                functionName: "freezeCollectionMetadata",
+                args: [],
+                account,
+                chain,
+            });
         },
         /** The launch this treasury opened. */
         async launched() {
@@ -291,7 +400,7 @@ export function createRipplesAgent(options = {}) {
     };
 }
 /** Whether this chain's factory deployed `treasury`, which is what makes its charter worth reading. */
-export async function readAgent(treasury, options = {}) {
+export async function isRipplesAgent(treasury, options = {}) {
     const network = options.network ?? "robinhood";
     const record = DEPLOYMENTS[network];
     const client = createPublicClient({
@@ -305,6 +414,98 @@ export async function readAgent(treasury, options = {}) {
         args: [treasury],
     });
 }
+const isSame = (left, right) => left.toLowerCase() === right.toLowerCase();
+/// A trade's deadline is an absolute moment on chain, and callers think in durations. This takes
+/// the seconds from now that a caller means and answers the moment the router wants.
+const deadline = (seconds = 300) => BigInt(Math.floor(Date.now() / 1000) + seconds);
+/** How far back `activity` looks when a caller names no range. */
+const DEFAULT_LOG_SPAN = 50000n;
+const MAX_UINT128 = (1n << 128n) - 1n;
+const MAX_UINT32 = 4_294_967_295;
+/** `Collection721.MAX_MINT_PER_TX`. */
+const MAX_MINT_PER_TX = 20;
+const MAX_ROYALTY_BPS = 1_000;
+const MAX_LOGO_BYTES = 512;
+const MAX_DESCRIPTION_BYTES = 2_048;
+const MAX_SOCIAL_BYTES = 256;
+const BPS = 10_000;
+const bytes = (value) => new TextEncoder().encode(value).length;
+/**
+ * The rules the chain holds, checked before a wallet is opened, and the two it cannot hold at
+ * all.
+ *
+ * A charter and a collection are created in one transaction and are both immutable afterwards,
+ * and nothing on chain compares them. A per-transaction limit under the mint price, or a wallet
+ * cap under the daily mint ceiling, deploys cleanly and leaves an agent that can never mint a
+ * single piece. This is the only place both halves are visible.
+ */
+function planned(plan, charter, quote) {
+    const { collection, token: identity } = plan;
+    const refuse = (why) => {
+        throw new RipplesAgentError(why);
+    };
+    if (!identity.image.trim())
+        refuse("A launch carries its image on chain, so `token.image` is required.");
+    if (bytes(identity.image) > MAX_LOGO_BYTES)
+        refuse(`\`token.image\` is over ${MAX_LOGO_BYTES} bytes.`);
+    if (bytes(identity.description ?? "") > MAX_DESCRIPTION_BYTES) {
+        refuse(`\`token.description\` is over ${MAX_DESCRIPTION_BYTES} bytes.`);
+    }
+    for (const [field, value] of Object.entries({
+        website: identity.website,
+        twitter: identity.twitter,
+        telegram: identity.telegram,
+        discord: identity.discord,
+        farcaster: identity.farcaster,
+    })) {
+        if (bytes(value ?? "") > MAX_SOCIAL_BYTES)
+            refuse(`\`token.${field}\` is over ${MAX_SOCIAL_BYTES} bytes.`);
+    }
+    if (collection.supply <= 0)
+        refuse("`collection.supply` has to be at least one.");
+    if ((collection.royaltyBps ?? 0) > MAX_ROYALTY_BPS) {
+        refuse(`\`collection.royaltyBps\` is at most ${MAX_ROYALTY_BPS}, which is 10%.`);
+    }
+    if (collection.endTime && collection.endTime * 1000 <= Date.now()) {
+        refuse("`collection.endTime` is in the past. Leave it out for a mint that never closes.");
+    }
+    // `Collection721` builds a token's URI by concatenating, so a base without a trailing slash
+    // produces `…/art1` rather than `…/art/1`.
+    if (!collection.baseUri.endsWith("/"))
+        refuse("`collection.baseUri` has to end in a slash.");
+    const linked = { ...LINKED_DEFAULTS, ...plan.linked };
+    if (linked.allocationBps <= 0 || linked.allocationBps >= BPS) {
+        refuse("`linked.allocationBps` is above zero and below 10000.");
+    }
+    if (linked.mintToCurveBps <= 0 || linked.mintToCurveBps > BPS) {
+        refuse("`linked.mintToCurveBps` is above zero and at most 10000.");
+    }
+    for (const [field, value] of Object.entries({
+        dailySpend: charter.dailySpend,
+        perCallSpend: charter.perCallSpend,
+        dailySell: charter.dailySell,
+    })) {
+        if (value > MAX_UINT128)
+            refuse(`\`charter.${field}\` is larger than the charter can carry.`);
+    }
+    if (charter.dailyMint > MAX_UINT32)
+        refuse("`charter.dailyMint` is larger than the charter can carry.");
+    // The two the chain never compares, and both of them are permanent.
+    const price = quote(collection.price);
+    if (charter.dailyMint > 0 && price > charter.perCallSpend) {
+        refuse("The agent could never mint: one piece costs more than `charter.perCallSpend` allows in a "
+            + "transaction, and neither figure can be changed after the launch.");
+    }
+    if (charter.dailyMint > 0 && price * BigInt(charter.dailyMint) > charter.dailySpend) {
+        refuse("`charter.dailyMint` pieces cost more than `charter.dailySpend`, so the mint ceiling can "
+            + "never be reached.");
+    }
+    const cap = collection.perWalletCap ?? 0;
+    if (cap > 0 && cap < charter.dailyMint) {
+        refuse("`collection.perWalletCap` counts the agent as one wallet, so it caps the agent's mints "
+            + "for life, below its own daily ceiling.");
+    }
+}
 function chartered(charter, quote, token) {
     const payees = charter.payees ?? [];
     if (payees.length > MAX_PAYEES) {
@@ -315,9 +516,19 @@ function chartered(charter, quote, token) {
     if (perCallSpend > dailySpend) {
         throw new RipplesAgentError("`perCallSpend` cannot be above `dailySpend`.");
     }
-    if (dailySpend > 0n && perCallSpend === 0n) {
+    if (perCallSpend === 0n) {
         throw new RipplesAgentError("A per-transaction limit of zero stops every payment the agent could make, for good.");
     }
+    if (!charter.operator || /^0x0+$/i.test(charter.operator)) {
+        throw new RipplesAgentError("`charter.operator` has to be a wallet that can sign.");
+    }
+    const seen = new Set(payees.map((payee) => payee.toLowerCase()));
+    if (seen.size !== payees.length) {
+        throw new RipplesAgentError("A charter names each payee once.");
+    }
+    if (payees.some((payee) => /^0x0+$/i.test(payee))) {
+        throw new RipplesAgentError("A payee cannot be the zero address.");
+    }
     return {
         operator: charter.operator,
         dailySpend,
@@ -331,8 +542,8 @@ async function readActivity(client, treasury, units) {
     const logs = await client.getLogs({
         address: treasury,
         events: AGENT_TREASURY_ABI.filter((entry) => entry.type === "event"),
-        fromBlock: 0n,
-        toBlock: "latest",
+        fromBlock: units.fromBlock,
+        toBlock: units.toBlock,
     });
     const ordered = [...logs].sort((left, right) => left.blockNumber === right.blockNumber
         ? Number((right.logIndex ?? 0n) - (left.logIndex ?? 0n))
@@ -344,8 +555,8 @@ async function readActivity(client, treasury, units) {
         const args = log.args ?? {};
         const name = log.eventName;
         const base = { block: log.blockNumber, transaction: log.transactionHash };
-        const q = (value) => units.showQuote((value ?? 0n));
-        const t = (value) => units.showToken((value ?? 0n));
+        const q = (value) => `${units.showQuote((value ?? 0n))} ${units.quoteSymbol}`;
+        const t = (value) => `${units.showToken((value ?? 0n))} ${units.tokenSymbol}`;
         switch (name) {
             case "Launched":
                 out.push({ kind: "launched", ...base, detail: `Opened its launch, token ${args.token}` });

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { DEPLOYMENTS, chainOf, type RipplesDeployment, type RipplesNetwork } from "./chains.js";
 export { LINKED_DEFAULTS, LINKED_RESERVES, MAX_PAYEES } from "./defaults.js";
 export { AGENT_FACTORY_ABI, AGENT_TREASURY_ABI } from "./abi.js";
-export { createRipplesAgent, readAgent, type Activity, type AgentCharter, type AgentClient, type Budget, type Charter, type CollectionPlan, type LaunchPlan, type LaunchResult, type RipplesAgentOptions, type TokenPlan, } from "./agent.js";
+export { createRipplesAgent, isRipplesAgent, RipplesAgentError, type Activity, type AgentCharter, type AgentClient, type Budget, type Charter, type CollectionPlan, type LaunchPlan, type LaunchResult, type RipplesAgentOptions, type TokenPlan, } from "./agent.js";

package/dist/index.js

@@ -1,4 +1,4 @@
 export { DEPLOYMENTS, chainOf } from "./chains.js";
 export { LINKED_DEFAULTS, LINKED_RESERVES, MAX_PAYEES } from "./defaults.js";
 export { AGENT_FACTORY_ABI, AGENT_TREASURY_ABI } from "./abi.js";
-export { createRipplesAgent, readAgent, } from "./agent.js";
+export { createRipplesAgent, isRipplesAgent, RipplesAgentError, } from "./agent.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ripplesdotrun/agent-sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Launch an agent on Ripples and run it: one call to create the market, the collection and the treasury that holds the agent's money under limits nobody can raise.",
   "keywords": [
     "ripples",
@@ -29,9 +29,10 @@
     "node": ">=20"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "prepublishOnly": "npm run build",
-    "test": "node --test test/*.test.mjs"
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "test": "node --test test/*.test.mjs",
+    "prepack": "npm run build",
+    "pretest": "npm run build"
   },
   "peerDependencies": {
     "viem": "^2.21.0"
@@ -43,10 +44,8 @@
   "publishConfig": {
     "access": "public"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/ripples-dot-run/ripples.git",
-    "directory": "packages/agent-sdk"
-  },
-  "homepage": "https://ripples.run/docs#rh-agents"
+  "homepage": "https://ripples.run/docs#rh-agents",
+  "bugs": {
+    "url": "https://ripples.run/docs#rh-agents"
+  }
 }