@peddles/sdk 0.2.0

package/CLAUDE_PROMPT.md

@@ -0,0 +1,159 @@
+# Integrate Peddles into your app — a prompt for Claude (or any coding agent)
+
+Copy everything between the lines below into Claude Code, Cursor, or any coding agent working in
+your repository. It gives the agent the SDK's surface and the rules a correct Peddles integration
+has to follow, so it can wire Peddles in without guessing.
+
+---
+
+You are integrating **Peddles** into this codebase using the `@peddles/sdk` TypeScript package
+(`npm i @peddles/sdk`, peer dependency `viem@^2`; source at github.com/peddles-markets/peddles-sdk). Peddles is a multi-chain
+launchpad for memecoins paired against **tokenised stocks** or ETH, on **Uniswap v4**, where every
+launch pool runs through one fee hook with terms fixed forever at launch. It also runs a **perp
+launchpad**: a coin whose v4 pool carries leveraged longs and shorts (Base and Robinhood Chain). Website: https://peddles.xyz ·
+docs: https://docs.peddles.xyz.
+
+## What to build
+
+Ask me which of these I want before writing code, then build only those:
+
+1. **Read** — show a launched token: name, symbol, decimals, supply, pool terms (tax, holder split),
+   holder rewards, clog state.
+2. **Launch** — let a user create a coin (ETH-paired, stock-paired, or Clog) and sign it in their own
+   wallet.
+3. **Trade links / discovery** — link tokens to their chain explorer and to https://peddleswap.xyz or
+   https://terminal.peddles.xyz.
+4. **NFT graduation** — Art→DEX / NFT→stock graduation requests and NFT-holder fee claims.
+5. **Perp market launch** — let a user create a perp market (`PeddlesPerpFactory.create`) and sign it.
+
+## Install
+
+```bash
+npm i @peddles/sdk viem
+```
+
+## The SDK surface you will use
+
+```ts
+// Root export: address book, reads, fee maths, ABIs, clog + NFT helpers
+import {
+  supportedChains, isKnownChain, addressOf, deploymentFor, DEPLOYMENTS,
+  UnknownChainError, UnknownContractError,
+  getTokenInfo, isVariantSupported, getPoolTerms, PoolTermsUnavailableError,
+  feeSplit, PLATFORM_FEE_BPS, CREATOR_FEE_BPS, MIN_CREATOR_TAX_BPS, MAX_CREATOR_TAX_BPS,
+  getVariantAllocation, getClogVault, getClogState, isReleaseReady, clogShareOfInflows,
+  relayParamsHash, stockGraduationOptInRequest, graduateToStockWithTermsRequest, graduateAndBuyRequest,
+  getHolderCommitment, getDistributorState, holderClaimable,
+  factoryAbi, feeHookAbi, stockLaunchpadAbi, erc20Abi, tokenV20Abi, holderRewardsAbi, /* … */
+} from '@peddles/sdk';
+
+// Launch builders: everything needed to produce an UNSIGNED launch tx { to, data, value }
+import {
+  launchAddressesFor, buildWethLaunchPlan, buildWethLaunchCall, encodeWethLaunchCall,
+  readOrchestratorLaunchFee, buildStockLaunchCall, encodeStockLaunchCall, encodeStockApproval,
+  readStockAllowance, readStockLaunchFee, readStockQuotes, isQuoteAllowed, predictStockCoin,
+  randomSalt, mineSalt, validateFeeTerms, feeSplitRate, parseTaxPercent, formatTaxPercent,
+  readLaunchVariants, variantForType, decodeLaunchRevert, explainLaunchRevert,
+} from '@peddles/sdk/launch';
+
+// Perps: the perp launchpad (PeddlesPerpFactory) — addresses, live base reads, create calldata
+import {
+  perpChains, hasPerps, perpContracts, PerpsUnavailableError, readPerpBase,
+  isValidPerpHookAddress, predictPerpHook, predictPerpToken, buildPerpCreate,
+  perpFactoryAbi, perpErrorsAbi, PERP_HOOK_FLAGS,
+} from '@peddles/sdk/perps';
+```
+
+Read the package's `README.md` and the `.d.ts` files in `node_modules/@peddles/sdk/dist` for exact
+signatures before calling anything; do not invent parameters.
+
+## Chains — resolve everything from the active chain, never hardcode one
+
+- Live today: **Base 8453 (mainnet)** and **Robinhood Chain 4663 (mainnet)**. Coming soon: Arc 5042, BNB Smart Chain 56. `supportedChains()` is the source of truth — call it, don't copy
+  this list.
+- Take the chain from the user's wallet / app config. If `isKnownChain(chainId)` is false, **disable the
+  Peddles feature and say so**; never fall back to another chain's addresses. The same contract name has
+  a different address on every chain, and a router or token address from one chain used on another is a
+  real-money bug.
+- External addresses (WETH, Uniswap PoolManager, stock tokens) differ per chain too — read them from the
+  chain (the launch plan does this: `buildWethLaunchPlan` reads the pool manager, WETH and hook from the
+  liquidity executor) rather than pasting constants.
+- Block times differ (Base ~2 s, Robinhood Chain counts Ethereum L1 blocks inside the EVM). Never convert
+  "blocks" to time with another chain's number.
+
+## Money rules — these are not optional
+
+1. **Never use a JS `number` for token amounts, prices or balances.** Use `bigint` in base units
+   everywhere; the SDK returns `bigint`. Convert with `viem`'s `parseUnits` / `formatUnits` only at the
+   input and render edges.
+2. **Every amount travels with its `decimals`.** Never assume 18: Coinbase B20 stock tokens on Base are
+   **8 decimals**, Robinhood stock tokens 18, USDG 6. `getTokenInfo()` returns decimals with the supply.
+3. **A tokenised stock is priced by its multiplier**, never one-to-one with the share
+   (`uiMultiplier()` on Robinhood/bStocks, `toScaledBalance()` on B20). Unknown price = show nothing.
+4. **Never invent a price or fall back to a stale one.** If a price source fails, render "unavailable".
+
+## Read order — chain first, API second
+
+- Read name, symbol, decimals, total supply, pool terms and lock status **from the chain** (the SDK's
+  read helpers do). A token page must work the moment the launch transaction confirms.
+- Use an off-chain API only for what the chain can't answer (logo, description, 24h volume, candles),
+  and when both answer, the chain wins.
+- Batch reads (`client.multicall`) and cache per block; don't hammer the RPC on every render.
+
+## Launching — the user signs, your code never holds keys
+
+- Build an **unsigned** tx with the SDK (`encodeWethLaunchCall` / `encodeStockLaunchCall` return
+  `{ to, data, value }`) and hand it to the user's wallet. Never ask for or store a private key.
+- **Read the launch fee from the chain** (`readOrchestratorLaunchFee`, `readStockLaunchFee`) — it is
+  owner-set per chain and changes; never hardcode it. Show it to the user before they sign.
+- **Fee terms are permanent.** `taxBps` (100–1000 = 1–10% all-in) and `excessToCreatorBps` are fixed in
+  the launch transaction and nobody can change them afterwards. Validate with `validateFeeTerms()` and
+  show the user the split from `feeSplitRate()` before they commit; say plainly that it is permanent.
+- Stock-paired launches: offer only quotes from `readStockQuotes()` / `isQuoteAllowed()`, and handle the
+  ERC-20 approval (`readStockAllowance` → `encodeStockApproval`) before the launch tx.
+- Check `isVariantSupported(client, chainId, variant)` before offering a launch type; a type that is not
+  registered on the chain must not be offered.
+- On failure, show `decodeLaunchRevert(error)` / `explainLaunchRevert(...)` — a reason in words, not a hex
+  blob. Never report success until the receipt says `status: success`.
+
+## Perps — launching a perp market
+
+- Perps exist only where `hasPerps(chainId)` is true (Base 8453, Robinhood Chain 4663).
+  `perpContracts(chainId)` throws on any other chain: disable the feature, never borrow another chain's
+  factory.
+- **Read the base live.** `readPerpBase(client, chainId, base)` returns `{ allowed, v, tickWidth }` as
+  bigints. Offer a base only while `allowed` is true; the creator has no curve choice, every market on a
+  base uses the factory's `v`/`tickWidth`. `baseCandidates` in `perpContracts()` is a list to ask about,
+  not an answer.
+- **You mine the hook salt.** Read `tokenInitCodeHash(name, symbol, tokenUri)` and then
+  `hookInitCodeHash(token)` from the factory, loop `predictPerpHook(hookDeployer, salt, hash)` from a
+  random 32-byte salt until `isValidPerpHookAddress(address)` (≈16k attempts — do it in a Web Worker),
+  then confirm both addresses with the factory's `predictToken` / `predictHook` before building.
+- `buildPerpCreate({...})` returns `{ to, data, value: 0n }`. `create` is not payable. An optional
+  `seedBuyBase` (bigint, base units) is pulled with `transferFrom`: approve exactly that amount to the
+  factory first, never an unlimited approval. Simulate before asking the user to sign; decode failures
+  with `perpErrorsAbi`.
+- Name, symbol and token URI are permanent. Perp contracts have no external audit — say so where a user
+  commits money.
+
+## UI rules
+
+- Token metadata (name, symbol, description, links, images) is **user-supplied and hostile**: escape it,
+  never use `dangerouslySetInnerHTML`, and label it "creator-supplied" where a user might trust it.
+- Show what costs money and what is permanent (launch fee, fee terms, dev buy). Don't show internal
+  contract names or mechanism to end users.
+- The first ~3 minutes of every pool carry a decaying **anti-sniper tax (20% → the pool's normal tax)**;
+  if your UI quotes a trade in that window, include it.
+
+## Done means
+
+- Type-checks with `strict`, no `any` on SDK values, no `number` for amounts.
+- A test or script that **reads live chain state** through your integration (e.g. `getTokenInfo` on a real
+  Base token) — a check that passes with the network unplugged hasn't tested anything.
+- Unknown chain, unknown token and RPC failure each render an honest, specific state instead of a
+  default.
+
+---
+
+*Maintained with the SDK at https://github.com/peddles-markets/peddles-sdk. Found a mismatch between this
+prompt and the SDK? The SDK's types win — please open an issue.*

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Peddles
+
+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

@@ -0,0 +1,186 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/peddles-markets/peddles-sdk/main/.github/og.png" alt="Peddles — Multi Chain Stock Pairs Launchpad" width="100%" />
+</p>
+
+# Peddles SDK
+
+TypeScript SDK for **[Peddles](https://peddles.xyz)** — the multi-chain launchpad for memecoins
+**paired against tokenised stocks** (and ETH), with a fixed-at-launch fee model, a built-in
+anti-sniper tax and holder rewards paid in the pool's own quote asset.
+
+Read launches from the chain, build launch transactions for your users to sign, and decode what
+went wrong when one reverts — with the same code the Peddles app runs.
+
+- 🌐 **Website:** [peddles.xyz](https://peddles.xyz) · **App:** [pro.peddles.xyz](https://pro.peddles.xyz) · **Swap:** [peddleswap.xyz](https://peddleswap.xyz) · **Terminal:** [terminal.peddles.xyz](https://terminal.peddles.xyz)
+- 📚 **Docs:** [docs.peddles.xyz](https://docs.peddles.xyz) · **Developers:** [dev.peddles.xyz](https://dev.peddles.xyz)
+- 🤖 **Integrating with an AI coding agent?** Paste [`CLAUDE_PROMPT.md`](./CLAUDE_PROMPT.md) into Claude (or any agent).
+
+---
+
+## Chains
+
+| Chain | Chain id | Status | Explorer |
+| --- | --- | --- | --- |
+| **Base** | 8453 | ✅ Live — mainnet | [base.blockscout.com](https://base.blockscout.com) · [basescan.org](https://basescan.org) |
+| **Robinhood Chain** | 4663 | ✅ Live — mainnet | [robin.etherscan.io](https://robin.etherscan.io) |
+| Arc | 5042 | 🔜 Coming soon | — |
+| BNB Smart Chain | 56 | 🔜 Coming soon | [bscscan.com](https://bscscan.com) |
+
+The SDK ships an address book **only for chains with a live deployment**. `supportedChains()` is the
+source of truth; a chain that is not in it throws `UnknownChainError` rather than falling back to
+another chain's addresses. Every address in `DEPLOYMENTS` was confirmed to have code on its chain
+before it was published (`npm run smoke` re-checks them live).
+
+## What Peddles does (what you can build on)
+
+| Feature | What it is |
+| --- | --- |
+| **Stock-paired launches** | A coin whose pool is paired against a tokenised stock (Coinbase B20 on Base, Robinhood tokens on 4663, bStocks on BSC). Holders are rewarded in that stock. |
+| **ETH-paired launches** | The classic shape — a coin paired against WETH on Uniswap v4. |
+| **Clog launches** | A launch type that holds back a slice of supply and releases it into the pool in small, time-spaced slices (≤ 3 hours for the whole clog). |
+| **Handle launches** | Launches whose creator fees accrue to an X (Twitter) account's pot, claimable by that account. |
+| **NFT bonding → DEX** | NFT collections sold on a bonding curve that graduate automatically into a DEX pool when they sell out. |
+| **Art → DEX / NFT → stock graduation** | Collections graduating into a stock-paired coin, with an optional share of fees committed to NFT holders. |
+| **One fee model, fixed at launch** | Every launch pool runs through `PeddlesFeeHook`: the creator picks an all-in tax (1–10%) and the split of the excess between themselves and holders **in the launch transaction**, and nobody can change either afterwards. |
+| **Anti-sniper opening tax** | 20% on the first block, decaying to the pool's normal tax over ~3 minutes. The creator's own buy in the launch transaction pays the normal rate. |
+| **Holder rewards** | Paid in the pool's quote asset (a TSLA-paired coin pays TSLA), deployed and bound inside the launch transaction. |
+| **Uniswap v4 venue** | Pools are native Uniswap v4 pools, identified by the Peddles fee hook address. |
+| **Perps** | A perp launchpad (`PeddlesPerpFactory`) on **Base** and **Robinhood Chain**: one transaction launches a coin whose v4 pool carries leveraged longs and shorts against its own liquidity. See [Perps](#perps). |
+
+Fee legs (constants in the contract, exposed by the SDK): **0.50% platform + 0.50% creator** are fixed
+inside every pool's tax; everything above them is split between the creator and holders at the
+creator's chosen ratio. `feeSplit()` computes it exactly.
+
+## Install
+
+```bash
+npm i @peddles/sdk viem
+```
+
+`viem` (v2) is a peer dependency. The package is ESM and ships its TypeScript types.
+
+## Quick start
+
+```ts
+import { createPublicClient, http } from 'viem';
+import { base } from 'viem/chains';
+import { supportedChains, addressOf, getTokenInfo, getPoolTerms, feeSplit } from '@peddles/sdk';
+
+const client = createPublicClient({ chain: base, transport: http() });
+
+supportedChains();                           // [4663, 8453]
+addressOf(8453, 'PeddlesFactoryV20');        // 0x90bD4d38F621529b4aD6480c221075B7317b1978
+
+// Identity and supply, read from the token itself — never assume 18 decimals.
+const info = await getTokenInfo(client, token);
+
+// The pool's permanent terms (tax, holder split, rewards distributor), read from the fee hook.
+const terms = await getPoolTerms(client, 8453, token);
+
+// Exactly where a fee goes. bigint in, bigint out — no floating point anywhere.
+const split = feeSplit(terms.creatorTaxBps, terms.excessToCreatorBps, 1_000_000n);
+```
+
+### Build a launch for a user to sign (ETH-paired)
+
+```ts
+import {
+  launchAddressesFor, buildWethLaunchPlan, buildWethLaunchCall, encodeWethLaunchCall,
+  readOrchestratorLaunchFee, randomSalt, validateFeeTerms, decodeLaunchRevert,
+} from '@peddles/sdk/launch';
+
+const addresses = launchAddressesFor(8453);
+const salt = randomSalt();   // or mineSalt({...}) for a vanity `…1978` token address, like the Peddles app
+const plan = await buildWethLaunchPlan(client, addresses, { salt, variant: 0 });   // 0 = plain launch
+const { launchFee: launchFeeWei } = await readOrchestratorLaunchFee(client, addresses.orchestrator); // read, never assumed
+
+const feeTerms = { taxBps: 300n, excessToCreatorBps: 5000n };                     // 3%, half the excess to holders
+const issue = validateFeeTerms(feeTerms);                                        // null when valid
+if (issue) throw new Error(`${issue.field}: ${issue.code}`);
+
+const call = buildWethLaunchCall(
+  { name: 'My Coin', symbol: 'MINE', salt, creator: user, feeTerms,
+    metadata: { contractUri: '', image: 'ipfs://…', website: '', x: '', telegram: '' },
+    plan, devBuyWei: 0n, minTokensOut: 0n, launchFeeWei },
+  addresses.orchestrator,
+);
+const tx = encodeWethLaunchCall(call, addresses.orchestrator);   // { to, data, value } — hand to the wallet
+
+// If it reverts, say why in words:
+try { /* send tx */ } catch (e) { console.log(decodeLaunchRevert(e)); }
+```
+
+Stock-paired launches use `buildStockLaunchCall` / `encodeStockLaunchCall` with `readStockQuotes()`
+(the whitelisted stock legs) and `readStockLaunchFee()`. Clog and NFT helpers live in the root export
+(`getClogState`, `clogShareOfInflows`, `graduateAndBuyRequest`, …).
+
+## Perps
+
+```ts
+import {
+  perpContracts, readPerpBase, predictPerpToken, predictPerpHook,
+  isValidPerpHookAddress, buildPerpCreate, perpFactoryAbi,
+} from '@peddles/sdk/perps';
+
+const { factory, hookDeployer, baseCandidates } = perpContracts(8453);   // or 4663; throws elsewhere
+
+// Is the base open for launches, and on what curve? Read live — never from a file.
+const weth = await readPerpBase(client, 8453, baseCandidates.WETH);
+if (!weth.allowed) throw new Error('perp launches on WETH are closed on this chain');
+
+// 1. The token address (any salt works).
+const tokenSalt = randomBytes32();
+const tokenHash = await client.readContract({ address: factory, abi: perpFactoryAbi,
+  functionName: 'tokenInitCodeHash', args: [name, symbol, tokenUri] });
+const token = predictPerpToken(factory, tokenSalt, tokenHash);
+
+// 2. MINE the hook salt: v4 reads a hook's permissions from the low 14 bits of its address.
+const hookHash = await client.readContract({ address: factory, abi: perpFactoryAbi,
+  functionName: 'hookInitCodeHash', args: [token] });
+let hookSalt = randomBytes32(), hook = predictPerpHook(hookDeployer, hookSalt, hookHash);
+while (!isValidPerpHookAddress(hook)) {           // ~16k attempts on average — run it in a Web Worker
+  hookSalt = increment(hookSalt);
+  hook = predictPerpHook(hookDeployer, hookSalt, hookHash);
+}
+// Confirm both with the factory's own predictToken / predictHook before building.
+
+// 3. The call. Not payable; a seed buy (bigint, base units) needs an exact approval to `factory` first.
+const tx = buildPerpCreate({ chainId: 8453, name, symbol, tokenUri, base: weth.base,
+  tokenSalt, hookSalt, seedBuyBase: 0n, hookAddress: hook });   // { to, data, value: 0n }
+```
+
+The Peddles app mines in a Web Worker over a preallocated `0xff ‖ deployer ‖ salt ‖ initCodeHash`
+buffer, bumping only the salt bytes — one keccak per attempt. Mining is left to the caller so you
+choose where it runs. Neither salt is bound to the sender: a copied pending `create` that lands first
+takes the addresses, and the original reverts having paid only gas.
+
+| Chain | Perps |
+| --- | --- |
+| Base 8453 | ✅ Live |
+| Robinhood Chain 4663 | ✅ Live |
+
+The perp contracts have **no external audit**.
+
+## Rules the SDK follows — and your integration should too
+
+1. **Money is `bigint` in base units, always.** Never route an amount through a JS `number`. Every
+   amount travels with its `decimals`; format only at the render edge. B20 stock legs on Base are
+   **8 decimals**, Robinhood's 18, USDG 6.
+2. **The chain is the source of truth.** Read a token's name, supply, decimals, pool terms and lock
+   status from the chain; use an API only for what the chain can't answer (logos, 24h volume, candles).
+3. **No silent defaults.** An unknown chain, token or venue throws. Never fall back to another chain.
+4. **A stock token is priced by its multiplier, never one-to-one with the share.**
+5. **Metadata is user-supplied and hostile.** Escape it; never render it as HTML.
+
+## Scripts
+
+```bash
+npm run build       # dist/
+npm test            # unit tests, including constants pinned against the contract sources
+npm run typecheck
+npm run smoke       # LIVE: every address in the book has code on its chain (read-only, no key)
+```
+
+## License
+
+MIT © Peddles

package/dist/abis.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The ABI fragments the SDK's public surface needs — and nothing else.
+ *
+ * DELIBERATELY PARTIAL. These are narrowed to the functions this package
+ * exposes, not dumps of the full artifacts. A published ABI is API: every
+ * fragment shipped here is one this package promises to keep working, so the
+ * ones an integrator has no business calling (owner setters, one-shot bootstrap
+ * calls, indexer hooks) are absent rather than available-but-undocumented.
+ *
+ * NARROWED, NOT HAND-TYPED. Which names ship is decided in
+ * `script/generate-abis.mjs`; every fragment's shape is copied from the
+ * compiler's own output (`contracts/out`) into `abis.generated.ts`.
+ *
+ * `PeddlesCreatorFeeHook` is intentionally absent: it is not part of the
+ * fixed-terms fee model. Every launch pool's terms are read from
+ * `PeddlesFeeHook` (`feeHookAbi`).
+ */
+export { factoryAbi, clogVaultAbi, clogVaultFactoryAbi, erc20Abi, tokenV20Abi, feeHookAbi, stockLaunchpadAbi, holderRewardsAbi, nftFactoryAbi, nftCollectionAbi, nftFeeDistributorFactoryAbi, nftFeeDistributorAbi, nftBondingGraduationOrchestratorAbi, nftStockGraduationOrchestratorAbi, liquidityExecutorAbi, routeSwapRouterAbi, } from './abis.generated.js';
+//# sourceMappingURL=abis.d.ts.map

package/dist/abis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abis.d.ts","sourceRoot":"","sources":["../src/abis.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EACL,UAAU,EACV,YAAY,EACZ,mBAAmB,EACnB,QAAQ,EACR,WAAW,EACX,UAAU,EACV,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,gBAAgB,EAChB,2BAA2B,EAC3B,oBAAoB,EACpB,mCAAmC,EACnC,iCAAiC,EACjC,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,qBAAqB,CAAC"}