fusorlabs-sdk 0.1.0__tar.gz

fusorlabs_sdk-0.1.0/.gitignore

@@ -0,0 +1,79 @@
+node_modules/
+.turbo/
+# .next-* 也要盖住：NEXT_DIST_DIR 会另起 dist 目录（.next-probe / .next-dev …），
+# 每个都带完整 standalone 产物（实测 835MB）。只写 .next/ 匹配不到它们。
+.next/
+**/.next-*/
+dist/
+out/
+coverage/
+*.tsbuildinfo
+
+# Foundry
+cache/
+broadcast/
+!broadcast/**/run-latest.json
+
+# 环境变量
+# ⚠️ `.env` 这一条只匹配**文件名恰好是 `.env`** 的，匹配不到 `.env.deploy`
+# —— 而那个文件里放的是部署者私钥。所以下面用 `.env.*` 兜住所有变体，
+# 再单独把 *.example 放出来（那些是要进版本库的模板）。
+# 负向规则必须写在 `.env.*` 之后，否则会被后面的规则覆盖掉。
+.env
+.env.*
+!.env.example
+!.env.*.example
+
+# 系统
+.DS_Store
+*.log
+
+# SDD 工作区（临时产物，不入库）
+.superpowers/
+out/
+out-v4/
+out-fork/
+# 每个 foundry profile 一个产物目录（见 packages/contracts/foundry.toml 的注释：
+# 刻意分开，避免两棵源码树的同名 artifact 互相覆盖）
+out-fusor/
+out-fusor-v4/
+out-split/
+out-deploy/
+cache/
+.image-cache/
+packages/contracts/lib/
+
+# Python SDK
+__pycache__/
+*.py[cod]
+.pytest_cache/
+*.egg-info/
+
+# ── 部署记录必须进版本库（这几条要放在**最后**）──
+# .gitignore 里有两条 `out/`（第 5、30 行），而 `out/` 匹配任何层级名叫 out 的目录，
+# 于是 packages/contracts/deploy/out/ 被连带忽略。那里放的是部署记录
+# （oracle-registry.json 是阶段 1 的 stockRegistry 来源，launchpad.json 是 SDK 的输入），
+# 丢了等于丢掉「我们部署在哪」这个事实。
+# 负向规则必须写在所有 `out/` 之后，否则会被后面的规则重新盖掉（踩过）。
+# 目录本身要先放出来，不然 git 根本不会往里走。
+!packages/contracts/deploy/out/
+!packages/contracts/deploy/out/*.json
+# 但 fork 演练产生的临时记录不要进
+packages/contracts/deploy/out/*.anvil.json
+
+# 部署密钥：绝不进版本库，也绝不进构建上下文
+secrets/
+deploy.env
+
+# 备份集：scripts/backup.sh 的产物。单次就有 190MB+
+# （postgres.dump + images.tar.gz + caddy-data.tar.gz），而且里面有库的全量数据
+# 与 TLS 私钥 —— 既不能进版本库，也不能进构建上下文（.dockerignore 同理）。
+# 异地存放的做法见 docs/ops/ingress-and-backup.md。
+backups/
+.vercel
+.env*.local
+
+# 发布凭据（npm / PyPI token）。放在仓库内本来就不该，但如果放了，
+# 至少不能被提交。发布完请立刻删除 —— 见 PROGRESS.md 的「发布」一节。
+sdks/.publish-npmrc
+sdks/.publish-pypirc

fusorlabs_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fusor Labs
+
+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 IN CONNECTION WITH THE SOFTWARE
+OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

fusorlabs_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.5
+Name: fusorlabs-sdk
+Version: 0.1.0
+Summary: One-line token launches on Fusor — bring your own private key
+Project-URL: Homepage, https://fusor.fun/docs
+Author: Fusor Labs
+License: MIT
+License-File: LICENSE
+Keywords: evm,fusor,launch,token,web3
+Requires-Python: >=3.11
+Requires-Dist: web3<8,>=7
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# fusorlabs-sdk
+
+One-line token launches on Fusor. Bring your own private key.
+
+```bash
+pip install fusorlabs-sdk
+```
+
+Requires Python 3.11+.
+
+## 一行发币
+
+```python
+import os
+from fusor import FusorClient
+
+fusor = FusorClient(
+    private_key=os.environ["PRIVATE_KEY"],
+)
+
+result = fusor.launch_token(
+    name="My Token",
+    symbol="MTK",
+    markets=["AAPL"],
+    metadata_uri="https://example.com/metadata.json",
+)
+print(result.token_address, result.explorer_url)
+```
+
+这一次调用内部完成 7 步：链上前置检查 → 解析并校验报价市场 → 预言机新鲜度 →
+元数据 → 构造参数 → 模拟 → 签名发送并等回执。
+
+## 先试一下，不花钱
+
+```python
+preview = fusor.launch_token(..., dry_run=True)
+print(preview.token_address)   # 预测地址
+print(preview.estimated_gas)
+print(preview.launch_fee_wei)  # 实读的发射费
+print(preview.params)          # 实际会编码的参数
+```
+
+`dry_run` 停在模拟：参数错、市场没启用、预言机陈旧都会在这里报出来，一笔交易都不发。
+
+⚠️ `dry_run` 返回的 `token_address` 是**预测**地址（按 launchpad 当前 nonce 算的
+CREATE 地址）。真发时如果有别人抢先落一笔，实际地址会不同 —— 所以不要拿它去预注册。
+真发时 `token_address` 来自回执的 `MultiPairLaunchCreated` 事件，是权威值。
+
+## 报价市场
+
+1 到 5 个。可以混用符号与地址：
+
+```python
+markets=["AAPL"]                          # 单个 → 100%
+markets=["AAPL", "TSLA"]                  # 两个 → 各 50%
+markets=["AAPL", "TSLA", "NVDA"]          # 三个 → 3334/3333/3333
+markets=[("AAPL", 6000), ("0xaf3d…", 4000)]  # 显式权重，必须合计 10000
+```
+
+不给权重就按数量均分（余数加在第一个上，保证合计精确等于 10000 —— 3333×3 = 9999
+会 revert `WeightsNotOneHundredPercent`）。要么全部给权重，要么全部不给，混用会报错。
+
+看有哪些符号可用：
+
+```python
+fusor.list_quote_markets()  # (QuoteAsset(symbol='AAPL', token='0xaf3d…', decimals=18), …)
+```
+
+符号表是内置的（股票代币注册表没有枚举接口，链上问不出来）。传地址则完全不依赖这张
+表 —— 每个地址都会实读 `registry.getConfig()` 校验 `enabled` / `decimals`。
+
+## 元数据
+
+两条路径。**传 `metadata_uri` 时 SDK 一次 HTTP 请求都不发**，只需要一个 RPC：
+
+```python
+fusor.launch_token(..., metadata_uri="https://example.com/metadata.json")
+```
+
+或者让 SDK 上传（需要配 `api_base_url`）：
+
+```python
+from fusor import TokenMetadata
+
+fusor = FusorClient(private_key=..., launchpad=..., api_base_url="https://api.example.com")
+
+fusor.launch_token(
+    name="My Token",
+    symbol="MTK",
+    markets=["AAPL"],
+    metadata=TokenMetadata(
+        description="…",
+        image="data:image/png;base64,…",   # 或一个已能公开访问的 http(s) URL
+        twitter="https://x.com/…",
+        website="https://…",
+    ),
+)
+```
+
+`metadata_hash` 是那段规范 JSON 字节的 keccak256（算的是我们提交的内容，不是服务端
+回给我们的哈希），所以链上的哈希永远对应实际提交的元数据。**规范 JSON 与 TS
+两个 SDK 逐字节一致** —— 同一份元数据在三个语言里得到同一个哈希。
+
+## 配置
+
+```python
+FusorClient(
+    private_key="0x…",       # 或 account=任意 eth_account LocalAccount（KMS / 硬件）
+    launchpad="0x…",         # 部署脚本产出折进 SDK 后可省略
+    chain_id=4663,           # 默认 Robinhood Chain
+    rpc_url="https://…",     # 覆盖默认 RPC（公共 RPC 有限流）
+    rpc_headers={...},       # 有的提供商用请求头鉴权
+    api_base_url="https://…",# 只有让 SDK 上传元数据时才需要
+)
+```
+
+`launchpad` **可以省略**（2026-09-06 起）—— 部署记录已经进了 spec 的 `deployments`，
+SDK 会按 `chain_id` 自动取。显式传入仍然优先，用于指向另一套部署。
+
+如果某条链在 spec 里没有部署记录，SDK 会**报错要求你显式传**，而不是去猜 ——
+更不会退回到别人的部署上。同一条链上就有别人的 launchpad，猜错的后果是把币
+发到不属于我们的合约里，而且不会有任何报错。
+
+## 错误处理
+
+失败会解成 32 个链上 custom error 之一。用 `error_name` 做程序化分支，**不要匹配文案**：
+
+```python
+from fusor import FusorConfigError, FusorPreflightError, FusorLaunchError
+
+try:
+    fusor.launch_token(...)
+except FusorConfigError:
+    pass   # 参数问题，一个请求都没发出去
+except FusorPreflightError as err:
+    pass   # 链上前置条件不满足，交易从未发出（预言机陈旧、市场没启用…）
+except FusorLaunchError as err:
+    if err.error_name == "StaleOracle":
+        pass   # 等 keeper 更新后重试
+```
+
+各语言 SDK 共用同一份错误文案，所以同一次 revert 在 TS 与 Python 里得到
+完全一样的报错。
+
+## 自己编排（KMS / 多签）
+
+每一步都单独导出，需要把交易交给外部签名器时可以自己拼：
+
+```python
+from fusor import preflight, resolve_markets, build_launch_params, simulate_launch, token_address_from_receipt
+
+pre = preflight(w3, launchpad)
+markets = resolve_markets(w3, pre.stock_registry, ["AAPL"])
+params = build_launch_params(..., markets=markets, creator=addr, deadline=...)
+sim = simulate_launch(w3, launchpad=launchpad, account=addr, params=params, launch_fee_wei=pre.launch_fee_wei)
+# → 自己构造并签名交易，回执用 token_address_from_receipt 解析
+```
+
+## 第一期不支持 developer buy
+
+发币同时用自己的钱买入（dev buy）需要移植定点 bonding-curve 数学并保证三个语言逐 wei
+一致，第一期不做。不带 dev buy 时发币是**单笔交易**。
+
+## 设计说明
+
+`launch_fee_wei` 与 `max_oracle_age` 是**部署期参数**，SDK 每次实读，不当常量。
+实现地址也**不 pin** —— 代理会升级，pin 地址会让所有用户在升级那一刻同时失效；
+SDK 改成扫实现字节码的 PUSH4 选择器做行为校验。
+
+完整设计记录见仓库的 `sdks/README.md`。
+
+## 测试
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e '.[dev]'
+.venv/bin/python -m pytest                    # 离线单测
+.venv/bin/python -m pytest tests_integration   # 对主网发**只读** RPC
+```
+
+两者刻意分开：`pyproject.toml` 的 `testpaths` 只指向 `tests`，所以集成测试默认
+不跑。它验证的是「SDK 内置的 spec 与我们**实际部署**的合约一致」—— 这类问题
+不会让任何离线测试变红。
+
+集成测试只发 `eth_call` / `eth_getCode`，**不发交易、不花钱**。传输层错误
+（限流、超时）一律 skip 而不是 fail —— 那说明的是端点状况，不是代码问题。
+
+可选：`FUSOR_RPC_URL` 换 RPC；`FUSOR_IT_FULL_SWEEP=1` 核对全部 60 个报价资产
+（默认只抽查 5 个，避免把公共 RPC 打到限流）。

fusorlabs_sdk-0.1.0/README.md

@@ -0,0 +1,188 @@
+# fusorlabs-sdk
+
+One-line token launches on Fusor. Bring your own private key.
+
+```bash
+pip install fusorlabs-sdk
+```
+
+Requires Python 3.11+.
+
+## 一行发币
+
+```python
+import os
+from fusor import FusorClient
+
+fusor = FusorClient(
+    private_key=os.environ["PRIVATE_KEY"],
+)
+
+result = fusor.launch_token(
+    name="My Token",
+    symbol="MTK",
+    markets=["AAPL"],
+    metadata_uri="https://example.com/metadata.json",
+)
+print(result.token_address, result.explorer_url)
+```
+
+这一次调用内部完成 7 步：链上前置检查 → 解析并校验报价市场 → 预言机新鲜度 →
+元数据 → 构造参数 → 模拟 → 签名发送并等回执。
+
+## 先试一下，不花钱
+
+```python
+preview = fusor.launch_token(..., dry_run=True)
+print(preview.token_address)   # 预测地址
+print(preview.estimated_gas)
+print(preview.launch_fee_wei)  # 实读的发射费
+print(preview.params)          # 实际会编码的参数
+```
+
+`dry_run` 停在模拟：参数错、市场没启用、预言机陈旧都会在这里报出来，一笔交易都不发。
+
+⚠️ `dry_run` 返回的 `token_address` 是**预测**地址（按 launchpad 当前 nonce 算的
+CREATE 地址）。真发时如果有别人抢先落一笔，实际地址会不同 —— 所以不要拿它去预注册。
+真发时 `token_address` 来自回执的 `MultiPairLaunchCreated` 事件，是权威值。
+
+## 报价市场
+
+1 到 5 个。可以混用符号与地址：
+
+```python
+markets=["AAPL"]                          # 单个 → 100%
+markets=["AAPL", "TSLA"]                  # 两个 → 各 50%
+markets=["AAPL", "TSLA", "NVDA"]          # 三个 → 3334/3333/3333
+markets=[("AAPL", 6000), ("0xaf3d…", 4000)]  # 显式权重，必须合计 10000
+```
+
+不给权重就按数量均分（余数加在第一个上，保证合计精确等于 10000 —— 3333×3 = 9999
+会 revert `WeightsNotOneHundredPercent`）。要么全部给权重，要么全部不给，混用会报错。
+
+看有哪些符号可用：
+
+```python
+fusor.list_quote_markets()  # (QuoteAsset(symbol='AAPL', token='0xaf3d…', decimals=18), …)
+```
+
+符号表是内置的（股票代币注册表没有枚举接口，链上问不出来）。传地址则完全不依赖这张
+表 —— 每个地址都会实读 `registry.getConfig()` 校验 `enabled` / `decimals`。
+
+## 元数据
+
+两条路径。**传 `metadata_uri` 时 SDK 一次 HTTP 请求都不发**，只需要一个 RPC：
+
+```python
+fusor.launch_token(..., metadata_uri="https://example.com/metadata.json")
+```
+
+或者让 SDK 上传（需要配 `api_base_url`）：
+
+```python
+from fusor import TokenMetadata
+
+fusor = FusorClient(private_key=..., launchpad=..., api_base_url="https://api.example.com")
+
+fusor.launch_token(
+    name="My Token",
+    symbol="MTK",
+    markets=["AAPL"],
+    metadata=TokenMetadata(
+        description="…",
+        image="data:image/png;base64,…",   # 或一个已能公开访问的 http(s) URL
+        twitter="https://x.com/…",
+        website="https://…",
+    ),
+)
+```
+
+`metadata_hash` 是那段规范 JSON 字节的 keccak256（算的是我们提交的内容，不是服务端
+回给我们的哈希），所以链上的哈希永远对应实际提交的元数据。**规范 JSON 与 TS
+两个 SDK 逐字节一致** —— 同一份元数据在三个语言里得到同一个哈希。
+
+## 配置
+
+```python
+FusorClient(
+    private_key="0x…",       # 或 account=任意 eth_account LocalAccount（KMS / 硬件）
+    launchpad="0x…",         # 部署脚本产出折进 SDK 后可省略
+    chain_id=4663,           # 默认 Robinhood Chain
+    rpc_url="https://…",     # 覆盖默认 RPC（公共 RPC 有限流）
+    rpc_headers={...},       # 有的提供商用请求头鉴权
+    api_base_url="https://…",# 只有让 SDK 上传元数据时才需要
+)
+```
+
+`launchpad` **可以省略**（2026-09-06 起）—— 部署记录已经进了 spec 的 `deployments`，
+SDK 会按 `chain_id` 自动取。显式传入仍然优先，用于指向另一套部署。
+
+如果某条链在 spec 里没有部署记录，SDK 会**报错要求你显式传**，而不是去猜 ——
+更不会退回到别人的部署上。同一条链上就有别人的 launchpad，猜错的后果是把币
+发到不属于我们的合约里，而且不会有任何报错。
+
+## 错误处理
+
+失败会解成 32 个链上 custom error 之一。用 `error_name` 做程序化分支，**不要匹配文案**：
+
+```python
+from fusor import FusorConfigError, FusorPreflightError, FusorLaunchError
+
+try:
+    fusor.launch_token(...)
+except FusorConfigError:
+    pass   # 参数问题，一个请求都没发出去
+except FusorPreflightError as err:
+    pass   # 链上前置条件不满足，交易从未发出（预言机陈旧、市场没启用…）
+except FusorLaunchError as err:
+    if err.error_name == "StaleOracle":
+        pass   # 等 keeper 更新后重试
+```
+
+各语言 SDK 共用同一份错误文案，所以同一次 revert 在 TS 与 Python 里得到
+完全一样的报错。
+
+## 自己编排（KMS / 多签）
+
+每一步都单独导出，需要把交易交给外部签名器时可以自己拼：
+
+```python
+from fusor import preflight, resolve_markets, build_launch_params, simulate_launch, token_address_from_receipt
+
+pre = preflight(w3, launchpad)
+markets = resolve_markets(w3, pre.stock_registry, ["AAPL"])
+params = build_launch_params(..., markets=markets, creator=addr, deadline=...)
+sim = simulate_launch(w3, launchpad=launchpad, account=addr, params=params, launch_fee_wei=pre.launch_fee_wei)
+# → 自己构造并签名交易，回执用 token_address_from_receipt 解析
+```
+
+## 第一期不支持 developer buy
+
+发币同时用自己的钱买入（dev buy）需要移植定点 bonding-curve 数学并保证三个语言逐 wei
+一致，第一期不做。不带 dev buy 时发币是**单笔交易**。
+
+## 设计说明
+
+`launch_fee_wei` 与 `max_oracle_age` 是**部署期参数**，SDK 每次实读，不当常量。
+实现地址也**不 pin** —— 代理会升级，pin 地址会让所有用户在升级那一刻同时失效；
+SDK 改成扫实现字节码的 PUSH4 选择器做行为校验。
+
+完整设计记录见仓库的 `sdks/README.md`。
+
+## 测试
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e '.[dev]'
+.venv/bin/python -m pytest                    # 离线单测
+.venv/bin/python -m pytest tests_integration   # 对主网发**只读** RPC
+```
+
+两者刻意分开：`pyproject.toml` 的 `testpaths` 只指向 `tests`，所以集成测试默认
+不跑。它验证的是「SDK 内置的 spec 与我们**实际部署**的合约一致」—— 这类问题
+不会让任何离线测试变红。
+
+集成测试只发 `eth_call` / `eth_getCode`，**不发交易、不花钱**。传输层错误
+（限流、超时）一律 skip 而不是 fail —— 那说明的是端点状况，不是代码问题。
+
+可选：`FUSOR_RPC_URL` 换 RPC；`FUSOR_IT_FULL_SWEEP=1` 核对全部 60 个报价资产
+（默认只抽查 5 个，避免把公共 RPC 打到限流）。

fusorlabs_sdk-0.1.0/fusor/__init__.py

@@ -0,0 +1,112 @@
+"""``fusor`` —— 一行发币。
+
+.. code-block:: python
+
+    import os
+    from fusor import FusorClient
+
+    fusor = FusorClient(private_key=os.environ["PRIVATE_KEY"], launchpad="0x…")
+    result = fusor.launch_token(
+        name="My Token",
+        symbol="MTK",
+        markets=["AAPL"],
+        metadata_uri="https://example.com/metadata.json",
+    )
+    print(result.token_address, result.explorer_url)
+
+高层就 ``FusorClient`` 一个类。下面还导出了每一步的独立函数
+（``preflight``、``resolve_markets``、``build_launch_params``…），给需要自己
+编排的用法 —— 比如把交易交给 KMS 或多签去签。
+"""
+
+from .client import DEFAULT_CHAIN_ID, DEFAULT_DEADLINE_SECONDS, FusorClient, LaunchResult
+from .errors import (
+    FusorConfigError,
+    FusorError,
+    FusorLaunchError,
+    FusorPreflightError,
+    decode_launch_error,
+)
+from .launch import (
+    LegacyLaunchParams,
+    SimulatedLaunch,
+    build_launch_params,
+    simulate_launch,
+    token_address_from_receipt,
+)
+from .markets import (
+    MarketInput,
+    ResolvedMarket,
+    decode_bytes32_symbol,
+    normalize_markets,
+    resolve_markets,
+)
+from .metadata import (
+    ResolvedMetadata,
+    TokenMetadata,
+    canonical_metadata_json,
+    hash_metadata,
+    resolve_metadata,
+)
+from .oracle import PriceReading, check_oracle_freshness, classify_price_reading
+from .preflight import Preflight, onchain_selectors, preflight
+from .spec import (
+    CHAINS,
+    CONSTANTS,
+    DEPLOYMENTS,
+    ERROR_MESSAGES,
+    FEED_ABI,
+    LAUNCH_SELECTOR,
+    LAUNCHPAD_ABI,
+    QUOTE_ASSETS,
+    REGISTRY_ABI,
+    QuoteAsset,
+    quote_asset_by_symbol,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "FusorClient",
+    "LaunchResult",
+    "DEFAULT_CHAIN_ID",
+    "DEFAULT_DEADLINE_SECONDS",
+    "FusorError",
+    "FusorConfigError",
+    "FusorPreflightError",
+    "FusorLaunchError",
+    "decode_launch_error",
+    "Preflight",
+    "preflight",
+    "onchain_selectors",
+    "MarketInput",
+    "ResolvedMarket",
+    "resolve_markets",
+    "normalize_markets",
+    "decode_bytes32_symbol",
+    "PriceReading",
+    "check_oracle_freshness",
+    "classify_price_reading",
+    "TokenMetadata",
+    "ResolvedMetadata",
+    "resolve_metadata",
+    "canonical_metadata_json",
+    "hash_metadata",
+    "LegacyLaunchParams",
+    "SimulatedLaunch",
+    "build_launch_params",
+    "simulate_launch",
+    "token_address_from_receipt",
+    "CONSTANTS",
+    "CHAINS",
+    "DEPLOYMENTS",
+    "QUOTE_ASSETS",
+    "QuoteAsset",
+    "quote_asset_by_symbol",
+    "LAUNCH_SELECTOR",
+    "LAUNCHPAD_ABI",
+    "REGISTRY_ABI",
+    "FEED_ABI",
+    "ERROR_MESSAGES",
+    "__version__",
+]