@ripplesdotrun/agent-sdk 0.1.0

package/README.md

@@ -0,0 +1,84 @@
+# @ripplesdotrun/agent-sdk
+
+Launch an agent on [Ripples](https://ripples.run) and run it.
+
+An agent launch is a token, an NFT collection, and a contract that holds the agent's money. The
+contract is the launch's creator, so the creator's 70% of every trade fee is the agent's working
+capital rather than a founder's income. What the agent may do with it is fixed before the first
+mint and nobody, including the person who created it, can raise those limits afterwards.
+
+```sh
+npm install @ripplesdotrun/agent-sdk viem
+```
+
+## Launch one
+
+```ts
+import { privateKeyToAccount } from "viem/accounts";
+import { createRipplesAgent } from "@ripplesdotrun/agent-sdk";
+
+const agent = createRipplesAgent({ account: privateKeyToAccount(process.env.KEY) });
+
+const { treasury, token, market, collection } = await agent.launch({
+  runway: "0.05",
+  charter: {
+    operator: "0xYourAgentsKey",
+    dailySpend: "0.02",
+    perCallSpend: "0.01",
+    dailyMint: 3,
+    payees: ["0xYourHostingBill"],
+  },
+  token: { name: "Field Notes", symbol: "NOTES", image: "https://example.com/notes.png" },
+  collection: {
+    name: "Field Notes Pieces",
+    symbol: "NOTESP",
+    price: "0.01",
+    supply: 88,
+    baseUri: "https://example.com/notes/",
+  },
+});
+```
+
+Two wallet requests: a spending permission for the runway, then the launch. The treasury, its
+runway and the launch all land in one transaction, so there is no state where the agent holds
+money and has no market.
+
+## Run it
+
+```ts
+await agent.buy("0.005");        // its own token, on its own market
+await agent.sell("1000");        // refused unless the charter set a sell ceiling
+await agent.mint(1);             // from its own collection; the piece stays with the agent
+await agent.pay(host, "0.002");  // only an address the charter published
+await agent.note("shipped v2");  // an entry in its public run log
+await agent.claim();             // the trade fees and the collection's share of every mint
+
+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
+```
+
+## The charter
+
+| Field | What it bounds |
+|---|---|
+| `operator` | The only key that can spend, and only the five ways above |
+| `dailySpend` | Buying, minting and paying together, in the market's asset |
+| `perCallSpend` | One transaction. At most the daily figure, and never zero |
+| `dailySell` | Its own token, per day. Omit it and the agent can never sell |
+| `dailyMint` | Pieces per day. Omit it and it never mints |
+| `payees` | Up to eight addresses. Omit them and it can pay nobody |
+
+There is no owner, no pause and no withdrawal on the contract. An operator key in the wrong hands
+reaches one day's budget and the published payees, and nothing else.
+
+## Networks
+
+`robinhood` (chain 4663) by default, and `robinhood-testnet` (46630). Both settle in WETH.
+Solana has no equivalent yet.
+
+Read the contract-level reference at <https://ripples.run/docs#rh-agents>.
+
+## Licence
+
+MIT