@masterpeach/launchpad-sdk 0.0.0-experimental-20260818121657

package/README.md

@@ -0,0 +1,262 @@
+# MasterPeach Launchpad SDK
+
+[简体中文](./README.zh-CN.md)
+
+Typed, Viem-only TypeScript SDK for the ARC Launchpad. It covers deployment resolution and
+verification, generated ABI bindings, on-chain reads and quotes, exact-amount approvals,
+simulate-then-send write pipelines, and receipt event decoding.
+
+The SDK's only consumer-provided dependency is `viem`. Shared amount, chain, transaction, and error
+primitives are bundled and re-exported from the root entry point. It ships no React hooks, no Wagmi
+adapter, and no Indexer client — those belong in the application layer.
+
+## Install
+
+```bash
+pnpm add @masterpeach/launchpad-sdk viem
+```
+
+## Entry points
+
+| Import | Contents |
+| --- | --- |
+| `@masterpeach/launchpad-sdk` | Client, actions, domain types, deployments, errors, pure helpers |
+| `@masterpeach/launchpad-sdk/abi` | Generated ABI bindings and the artifact commit |
+
+Frontend integration is covered in depth in
+[docs/integration-guide.en.md](./docs/integration-guide.en.md)
+([简体中文](./docs/integration-guide.md)), including a Wagmi adapter, query keys, and a migration
+checklist.
+
+## Deployments and capabilities
+
+Arc is **testnet-only** today; no mainnet exists. The built-in production registry is therefore
+empty by design and reserved for a future verified manifest. The Arc Testnet V2 deployment is
+exported by name so it must be opted into explicitly.
+
+The typed client is configured from a **chain config**, which carries the verified deployment *and*
+the product capabilities. One object means there is no second source to drift, and the write gate
+cannot be skipped by construction.
+
+```ts
+import {
+  arcTestnetLaunchpadDeployment,
+  createLaunchpadPortalClient,
+  defineLaunchpadChain,
+  verifyLaunchpadDeployment,
+} from "@masterpeach/launchpad-sdk";
+
+const chain = defineLaunchpadChain({
+  slug: "arc-testnet",
+  chainId: arcTestnetLaunchpadDeployment.chainId,
+  family: "evm",
+  nativeCurrency: { symbol: "USDC", decimals: 18 },
+  rpcUrls: ["https://rpc.testnet.arc.io"],
+  explorerUrl: "https://testnet.arcscan.app",
+  apiBaseUrl: "https://your-indexer.example",
+  realtimeUrl: "wss://rpc.testnet.arc.io",
+  deployment: arcTestnetLaunchpadDeployment,
+  quoteTokens: [
+    { address: arcTestnetLaunchpadDeployment.contracts.quoteToken, decimals: 6, symbol: "tUSDC" },
+  ],
+  capabilities: {
+    create: true,
+    bondingTrade: true,
+    graduatedTrade: false, // no audited router yet
+    antiFarmer: true,
+    earlySellTax: false,
+    rewards: false,        // Locker claim off until the product confirms it
+    referral: false,
+  },
+  confirmations: 2,
+});
+
+// Confirms chain id, Portal runtime bytecode hash, and every module binding before use.
+await verifyLaunchpadDeployment(publicClient, chain.deployment);
+
+const client = createLaunchpadPortalClient({ publicClient, walletClient, chain });
+```
+
+When Arc mainnet ships, register its manifest the same way — call sites do not change.
+
+Write paths are gated by these capabilities and throw `UnsupportedLaunchpadCapabilityError`:
+`prepareCreateToken` needs `create`, `prepareBuy`/`prepareSell` need `bondingTrade`, and
+`prepareClaimReward` needs `rewards` (off by default). `prepareMigration` and `prepareCollectFees`
+are **not** gated — both are permissionless on-chain, and disabling migration would strand
+graduated tokens while disabling collection would freeze fees that belong to creators. Reads are
+never gated, so a page renders without a signer regardless of which writes are enabled.
+
+## Reading
+
+Every read accepts `blockNumber` / `blockTag`, so state, quotes, balances, and allowances can be
+pinned to one block instead of stitched from different heights.
+
+```ts
+const blockNumber = await publicClient.getBlockNumber();
+const [state, quote, availability] = await Promise.all([
+  client.getTokenState(token, { blockNumber }),
+  client.quoteBuy(token, parseUnits("100", 6), { blockNumber }),
+  client.getTradeAvailability(token, { blockNumber }),
+]);
+```
+
+`getTradeAvailability` and `getPrice` are composite reads and are **strictly same-block**: they
+resolve one height first, then pin their sub-reads to it, so a fee can never be computed for one
+block from another block's state. `latest`, `safe`, `finalized`, and an explicit height behave
+identically; `pending` has no stable height and is rejected with `UnpinnableBlockTagError`.
+
+`getPrice` returns the **bonding-curve reference price**, tagged with its `source` and the `phase`
+observed at read time. It is never an executable quote, it must not be used to derive a `minOut`,
+and after graduation it does not track the V3 pool — read the official pool or your indexer for a
+live DEX price.
+
+## Trading
+
+Writes follow one pipeline: validate → refresh quote → derive a non-zero minimum → check the exact
+allowance → `simulateContract` → `writeContract`. Nothing is broadcast without a simulation.
+
+```ts
+import { toDeadline } from "@masterpeach/launchpad-sdk";
+
+const block = await publicClient.getBlock();
+const prepared = await client.prepareBuy({
+  token,
+  quoteIn,
+  slippage: { bps: 100 },          // capped at 10%
+  deadline: toDeadline(block.timestamp),
+});
+
+const hash = await client.send(prepared);
+const result = await client.wait(hash);
+const trade = result.events.trades[0];
+```
+
+Approvals are **exact-amount** by default and the spender is always the Portal. An unlimited
+allowance requires passing `maxUint256` explicitly. For a buy, approve `quote.quoteSpent` rather
+than the user's typed input — a graduating buy spends less than requested.
+
+### Creating a token
+
+Pass `slippage` and the SDK prices the creator's atomic first buy against the deployed curve, then
+derives a safe non-zero `minInitialTokenOut` from it:
+
+```ts
+const prepared = await client.prepareCreateToken({
+  name,
+  symbol,
+  metadata: JSON.stringify({ description, image, website }),
+  userSalt: keccak256(crypto.getRandomValues(new Uint8Array(32))),
+  initialQuoteIn,             // 0n for no first buy
+  slippage: { bps: 100 },     // required when initialQuoteIn > 0
+  deadline: toDeadline(block.timestamp),
+  protectionBlocks: 6,        // 0..6
+});
+
+prepared.preview.firstBuy;            // the full quote behind the minimum
+prepared.preview.minInitialTokenOut;  // what will actually be submitted
+```
+
+The allowance is checked against `quoteSpent` rather than `initialQuoteIn`, because a first buy that
+reaches graduation is truncated at the threshold and transfers less than committed — while the
+simulation still submits the raw `initialQuoteIn`, since the Portal performs that truncation itself.
+`minInitialTokenOut` may be supplied instead of `slippage` when you compute it yourself; it must be
+positive and within the fresh quote, so there is no unsafe zero-minimum path.
+
+### prepare → send is re-validated
+
+A prepared transaction carries the chain, account, and Portal it was simulated under, and `send`
+re-reads the wallet's live chain and account before broadcasting:
+
+| Situation | Error |
+| --- | --- |
+| Wallet switched network after prepare | `WrongWalletChainError` |
+| Wallet switched account after prepare | `PreparedAccountMismatchError` |
+| Prepared for another deployment, or not minted by this client | `ForgedPreparedTransactionError` |
+
+Prepare and send through the same client instance, and re-prepare after any wallet change rather
+than retrying a stale prepared value.
+
+## Events
+
+`Trade.quoteAmount` is asymmetric on-chain: the Portal emits the **net** quote on a buy and the
+**gross** quote on a sell. The decoder preserves the raw value and adds unambiguous signed deltas,
+so volume is never computed from a field that changes meaning by direction.
+
+```ts
+const { trades, tokenCreated, migrationStarted } = result.events;
+trades[0].traderQuoteDelta;   // buy: -(raw + fee), sell: +(raw - fee)
+trades[0].reserveQuoteDelta;  // buy: +raw,         sell: -raw
+```
+
+The created token address comes from the `TokenCreated` event, never from a predicted address.
+
+## Errors
+
+Contract failures are classified by decoded custom-error name, not message text:
+
+| Contract revert | SDK error |
+| --- | --- |
+| `InvalidStatus` | `LaunchpadPhaseUnavailableError` |
+| `ProtocolPaused` | `LaunchpadTradingPausedError` |
+| `LaunchBlockTradingDisabled` | `LaunchpadProtectionError` |
+| `SlippageExceeded` | `LaunchpadSlippageError` |
+| `DeadlineExpired` | `LaunchpadDeadlineExpiredError` |
+| insufficient allowance | `LaunchpadApprovalRequiredError` |
+| insufficient balance | `LaunchpadInsufficientBalanceError` |
+| `OfficialPoolLocked` | `LaunchpadOfficialPoolLockedError` |
+| unregistered LP NFT id | `LaunchpadUnknownPositionError` |
+| wallet on the wrong chain | `WrongWalletChainError` |
+| wallet switched account after prepare | `PreparedAccountMismatchError` |
+| prepared value from elsewhere | `ForgedPreparedTransactionError` |
+| capability disabled for this chain | `UnsupportedLaunchpadCapabilityError` |
+| non-pinnable block tag on a composite read | `UnpinnableBlockTagError` |
+
+Unrecognized failures fall back to the SDK's shared error codes with the cause preserved.
+
+### Using more than one MasterPeach SDK
+
+Shared primitives are exported from the `./core` subpath, never from the root entry point, so the
+root entry points of two MasterPeach SDKs never export the same name. Import them from one SDK's
+`./core`:
+
+```ts
+import { isPeachSdkError, parseAmount } from "@masterpeach/launchpad-sdk/core";
+```
+
+Each SDK still bundles its own copy, so the shared error classes are distinct objects in each
+package. Use the `isPeachSdkError` guard, not `instanceof`:
+
+```ts
+import { isPeachSdkError } from "@masterpeach/launchpad-sdk/core";
+
+if (isPeachSdkError(error, "UNSUPPORTED_CHAIN")) {
+  // Matches whether launchpad-sdk or lending-sdk raised it.
+}
+```
+
+The guard brands errors through the global symbol registry, so every copy recognizes the others'.
+`PeachSdkErrorCode` values are the stable contract to branch on. Launchpad-specific errors above
+exist only in this package and are exported from the root entry point, so `instanceof
+LaunchpadError` remains correct for them.
+
+## Regenerating the ABI
+
+ABI is generated from Foundry artifacts built at a pinned contract revision; it is never
+hand-written or copied from an application.
+
+```bash
+# in the contracts repo, at the pinned revision
+forge build
+
+pnpm abi:generate \
+  --config tooling/abi-codegen/launchpad-artifacts.json \
+  --artifacts-root <contracts>/contracts/out \
+  --output-dir packages/launchpad/src/abi/generated \
+  --artifact-commit <40-char commit>
+```
+
+## Scope
+
+Not included: Tax tokens, referrals, bridges, DEX aggregator swaps, protocol-owner entry points,
+or V3 LP management. Graduated (post-migration) trading stays quote-only until an audited router
+contract exists.

package/README.zh-CN.md

@@ -0,0 +1,242 @@
+# MasterPeach Launchpad SDK
+
+[English](./README.md)
+
+面向 ARC Launchpad 的类型化 TypeScript SDK，仅依赖 Viem。覆盖部署解析与校验、生成式 ABI 绑定、
+链上只读与报价、精确额度授权、先模拟后广播的写入管线，以及回执事件解码。
+
+SDK 唯一需要消费端提供的依赖是 `viem`。金额、网络、交易和错误等共享基础能力已内联，并从根入口
+重新导出。SDK 不包含 React hooks、Wagmi adapter 或 Indexer 客户端 —— 这些属于应用层。
+
+## 安装
+
+```bash
+pnpm add @masterpeach/launchpad-sdk viem
+```
+
+## 入口
+
+| 导入路径 | 内容 |
+| --- | --- |
+| `@masterpeach/launchpad-sdk` | 客户端、actions、领域类型、部署、错误、纯函数 |
+| `@masterpeach/launchpad-sdk/abi` | 生成的 ABI 绑定与 artifact commit |
+
+前端接入的完整说明见 [docs/integration-guide.md](./docs/integration-guide.md)
+([English](./docs/integration-guide.en.md))，含 Wagmi adapter、query key 与迁移清单。
+
+## 部署与 capability
+
+Arc 目前**只有测试网**，正式网尚未上线。因此内置的生产 registry 刻意保持为空，作为未来经核验
+manifest 的预留入口。Arc Testnet V2 以具名方式导出，必须显式接入。
+
+类型化客户端由 **chain config** 构造，它同时携带经校验的 deployment **和**产品 capabilities。
+配置只有一个真源，不存在第二处可漂移，写入门禁也无法被绕过。
+
+```ts
+import {
+  arcTestnetLaunchpadDeployment,
+  createLaunchpadPortalClient,
+  defineLaunchpadChain,
+  verifyLaunchpadDeployment,
+} from "@masterpeach/launchpad-sdk";
+
+const chain = defineLaunchpadChain({
+  slug: "arc-testnet",
+  chainId: arcTestnetLaunchpadDeployment.chainId,
+  family: "evm",
+  nativeCurrency: { symbol: "USDC", decimals: 18 },
+  rpcUrls: ["https://rpc.testnet.arc.io"],
+  explorerUrl: "https://testnet.arcscan.app",
+  apiBaseUrl: "https://your-indexer.example",
+  realtimeUrl: "wss://rpc.testnet.arc.io",
+  deployment: arcTestnetLaunchpadDeployment,
+  quoteTokens: [
+    { address: arcTestnetLaunchpadDeployment.contracts.quoteToken, decimals: 6, symbol: "tUSDC" },
+  ],
+  capabilities: {
+    create: true,
+    bondingTrade: true,
+    graduatedTrade: false, // 尚无经审计的 Router
+    antiFarmer: true,
+    earlySellTax: false,
+    rewards: false,        // Locker claim 在产品确认前保持关闭
+    referral: false,
+  },
+  confirmations: 2,
+});
+
+// 校验链 ID、Portal runtime bytecode hash 及全部模块绑定。
+await verifyLaunchpadDeployment(publicClient, chain.deployment);
+
+const client = createLaunchpadPortalClient({ publicClient, walletClient, chain });
+```
+
+正式网上线后按同样方式注册 manifest，调用方代码无需改动。
+
+写入路径受上述 capabilities 门控，不满足时抛 `UnsupportedLaunchpadCapabilityError`：
+`prepareCreateToken` 需要 `create`，`prepareBuy`/`prepareSell` 需要 `bondingTrade`，
+`prepareClaimReward` 需要 `rewards`（默认关闭）。`prepareMigration` 与 `prepareCollectFees` **不**受
+门控 —— 两者在链上都是 permissionless；禁用迁移会让已毕业的 Token 卡住，禁用手续费收取则会冻住
+本属于 creator 的收益。读取永不受门控，因此页面在无签名者时也能渲染。
+
+## 读取
+
+所有 read 都接受 `blockNumber` / `blockTag`，可以把状态、报价、余额和 allowance 固定在同一个区块，
+避免拼接不同高度的数据。
+
+```ts
+const blockNumber = await publicClient.getBlockNumber();
+const [state, quote, availability] = await Promise.all([
+  client.getTokenState(token, { blockNumber }),
+  client.quoteBuy(token, parseUnits("100", 6), { blockNumber }),
+  client.getTradeAvailability(token, { blockNumber }),
+]);
+```
+
+`getTradeAvailability` 与 `getPrice` 是组合读取，**严格同块**：先解析出一个确定高度，再把各子读取
+固定到它，因此不会用某个区块的状态去计算另一个区块的费率。`latest`、`safe`、`finalized` 与显式高度
+语义一致；`pending` 没有稳定高度，会以 `UnpinnableBlockTagError` 拒绝。
+
+`getPrice` 返回的是**曲线参考价**，并标注 `source` 与读取时的 `phase`。它不是可执行报价，不能用来
+计算 `minOut`；毕业之后它也不会跟随 V3 池价格，实时 DEX 价格请从官方 Pool 或 Indexer 获取。
+
+## 交易
+
+写入统一遵循：参数校验 → 刷新报价 → 计算非零最小输出 → 检查精确授权 → `simulateContract` →
+`writeContract`。没有经过模拟的交易不会被广播。
+
+```ts
+import { toDeadline } from "@masterpeach/launchpad-sdk";
+
+const block = await publicClient.getBlock();
+const prepared = await client.prepareBuy({
+  token,
+  quoteIn,
+  slippage: { bps: 100 },          // 上限 10%
+  deadline: toDeadline(block.timestamp),
+});
+
+const hash = await client.send(prepared);
+const result = await client.wait(hash);
+```
+
+授权默认是**精确额度**，spender 恒为 Portal。无限授权必须显式传入 `maxUint256`。买入时应按
+`quote.quoteSpent` 授权，而不是用户输入值 —— 触达毕业的买入实际花费会更少。
+
+### 创建 Token
+
+传入 `slippage`，SDK 会用已部署的 curve 为 creator 原子首购报价，并据此推导安全的非零
+`minInitialTokenOut`：
+
+```ts
+const prepared = await client.prepareCreateToken({
+  name,
+  symbol,
+  metadata: JSON.stringify({ description, image, website }),
+  userSalt: keccak256(crypto.getRandomValues(new Uint8Array(32))),
+  initialQuoteIn,             // 不首购则传 0n
+  slippage: { bps: 100 },     // initialQuoteIn > 0 时必填
+  deadline: toDeadline(block.timestamp),
+  protectionBlocks: 6,        // 0..6
+});
+
+prepared.preview.firstBuy;            // 推导最小值所依据的完整报价
+prepared.preview.minInitialTokenOut;  // 实际提交的值
+```
+
+allowance 按 `quoteSpent` 而非 `initialQuoteIn` 检查 —— 触达毕业阈值的首购会被截断，实际转账少于
+承诺额；而 simulation 仍提交原始 `initialQuoteIn`，因为截断由 Portal 自己完成。若你自行计算最小值，
+可用 `minInitialTokenOut` 替代 `slippage`，它必须为正且不超过实时报价，因此不存在零最小值的不安全
+路径。
+
+### prepare → send 会二次校验
+
+prepared transaction 携带它被模拟时的 chain、account 与 Portal，`send` 在广播前会重新读取钱包的
+实时 chain 与 account：
+
+| 场景 | 错误 |
+| --- | --- |
+| prepare 后钱包切换了网络 | `WrongWalletChainError` |
+| prepare 后钱包切换了账户 | `PreparedAccountMismatchError` |
+| 属于其他 deployment，或非本 client 产出 | `ForgedPreparedTransactionError` |
+
+prepare 与 send 请用同一个 client 实例；钱包发生任何变化后重新 prepare，不要重试过期的 prepared 值。
+
+## 事件
+
+链上 `Trade.quoteAmount` 语义不对称：买入记录**扣费后**的 net，卖出记录**扣费前**的 gross。
+解码器保留原始值，并额外给出方向明确的有符号增量，避免用一个含义随方向变化的字段统计成交量。
+
+```ts
+trades[0].traderQuoteDelta;   // 买: -(raw + fee)，卖: +(raw - fee)
+trades[0].reserveQuoteDelta;  // 买: +raw，       卖: -raw
+```
+
+新建 Token 地址一律取自 `TokenCreated` 事件，不使用预测地址。
+
+## 错误
+
+合约失败按解码出的 custom error 名称分类，不依赖错误文本：
+
+| 合约 revert | SDK 错误 |
+| --- | --- |
+| `InvalidStatus` | `LaunchpadPhaseUnavailableError` |
+| `ProtocolPaused` | `LaunchpadTradingPausedError` |
+| `LaunchBlockTradingDisabled` | `LaunchpadProtectionError` |
+| `SlippageExceeded` | `LaunchpadSlippageError` |
+| `DeadlineExpired` | `LaunchpadDeadlineExpiredError` |
+| allowance 不足 | `LaunchpadApprovalRequiredError` |
+| 余额不足 | `LaunchpadInsufficientBalanceError` |
+| `OfficialPoolLocked` | `LaunchpadOfficialPoolLockedError` |
+| LP NFT 编号未注册 | `LaunchpadUnknownPositionError` |
+| 钱包链不匹配 | `WrongWalletChainError` |
+| prepare 后切换了账户 | `PreparedAccountMismatchError` |
+| prepared 值来源不明 | `ForgedPreparedTransactionError` |
+| 该链 capability 已关闭 | `UnsupportedLaunchpadCapabilityError` |
+| 组合读取传入不可固定的 block tag | `UnpinnableBlockTagError` |
+
+未识别的失败回退到 SDK 的共享错误码，并保留 cause。
+
+### 同时使用多个 MasterPeach SDK
+
+共享基础能力统一从 `./core` 子路径导出，**不会**出现在根入口，因此两个 MasterPeach SDK 的根入口不存在
+同名导出，同时引入不会冲突。需要共享能力时，从任一 SDK 的 `./core` 导入：
+
+```ts
+import { isPeachSdkError, parseAmount } from "@masterpeach/launchpad-sdk/core";
+```
+
+每个 SDK 仍会内联各自的副本，因此共享错误类在各 Package 中是**互相独立的对象**。请使用
+`isPeachSdkError` 判别，而不是 `instanceof`：
+
+```ts
+import { isPeachSdkError } from "@masterpeach/launchpad-sdk/core";
+
+if (isPeachSdkError(error, "UNSUPPORTED_CHAIN")) {
+  // 无论由 launchpad-sdk 还是 lending-sdk 抛出都成立。
+}
+```
+
+该 Guard 通过全局 Symbol 注册表为错误打标记，因此每份副本都能识别其他副本抛出的错误。分支判断应以
+`PeachSdkErrorCode` 取值为稳定契约。上表中的 Launchpad 专有错误只存在于本 Package 且从根入口导出，
+仍应使用 `instanceof LaunchpadError` 判别。
+
+## 重新生成 ABI
+
+ABI 由固定合约 revision 的 Foundry artifact 生成，禁止手写或从应用侧复制。
+
+```bash
+# 在合约仓库的固定 revision 上
+forge build
+
+pnpm abi:generate \
+  --config tooling/abi-codegen/launchpad-artifacts.json \
+  --artifacts-root <contracts>/contracts/out \
+  --output-dir packages/launchpad/src/abi/generated \
+  --artifact-commit <40 位 commit>
+```
+
+## 范围
+
+不包含：Tax Token、Referral、跨链桥、聚合器 DEX Swap、协议 Owner 管理入口、V3 LP 管理。
+毕业后的交易在经过审计的 Router 合约发布前保持 quote-only。