bounded-onchain

Bounded 链上

钱包、代币、链上交易和支付。规范的 Bounded 邮箱／社交登录默认包含钱包：保留默认的 Turnkey 身份验证和受支持的邮箱／社交登录，即可获得真实的 @user.address——参见 docs/embedded-wallets.md。@user.id（账户 ID）仍是身份／所有权标识；@user.address 则是钱包。链上写入仍须先通过策略规则和不变量检查，因此请将其与 bounded-backend 技能搭配使用，以遵循相关规则。若要在整个技能系列中路由，请参见根目录的 bounded 技能。

参考路由器

只阅读与当前任务或术语匹配的行。

任务或术语	阅读
快速查找插件命名空间或函数	插件目录 - 精简的命名空间／函数路由器
浏览所有不带修饰的签名和可调用上下文	完整签名索引
某个插件函数的准确签名、清单参数说明和签名者标记、返回类型及可调用上下文	插件目录，然后查看 docs/plugins/ 下对应的命名空间页面
Token-2022 转账税、钱包／金库中代扣的费用、铸币账户费用归集、专用提取权限、作为费用接收方的金库、待领取款项	转账费用归集
谁持有资金、谁签名、托管账户与命名 PDA 和用户钱包的区别、@AccountPlugin.createAccount、账户 ID 规范、创建－注资－使用惯用模式	托管与 PDA
托管、金库、资金库、质押、市场、发行、NFT、Token-2022、随机数或流动性应用的完整策略	示例索引
链上写入失败：错误查询、租金、ATA 付款方、交易限制、确认、环境差异	链上故障排查
在 Poofnet 上使用模拟 SOL、USDC 或其他代币为任意钱包注资、bounded wallet fund、realtime_offchain	Poofnet 链上模拟
SOLANA_DEVNET_RPC_URL is required、SOLANA_MAINNET_RPC_URL、validate pre-built transaction、签名前提交失败、没有 --rpc-url 标志、回退到公共 RPC	CLI 提交需要显式指定 RPC 端点
浏览器端链上 set() 无法提交、init() 中的 chain、默认 Helius RPC、可选的顶层 rpcUrl 覆盖项	浏览器／SDK 的 RPC 默认值与覆盖项
onchain account resolution failed (422)、onchain account not found: <pubkey>、写入时指定了链上不存在的账户、mint／池地址派生错误、getTokenMintAddress 的 1 参数与 3 参数调用不匹配	链上账户缺失与平台 502 错误的区别
onchain account resolution failed (502)、onchain query failed (502)、没有 403 也没有 422 时出现 Transaction building failed、命名查询和普通 getBalance 同时失败、平台解析器故障	平台解析器与链上查询 502 错误
Pump.fun 发行签名后失败并显示 insufficient lamports（need 1461600、Create Metadata Accounts v3）、由应用托管的创建者注资	错误表和代币发行示例
链上集合、onchain:true、--protocol、Solana、主网许可、补丁、只读 !、FieldReadOnly	链上
编译器与已部署功能支持、devnet 状态、受阻或未经验证的集成（Jupiter、Phoenix、DFlow、Kamino、Pump.fun、PumpSwap、Tensor、SPL stake pool、liquid staking、Raydium CPMM、Meteora DLMM）、runtime-v4 门控	功能支持状态
Helius、镜像／索引器、遗漏的交易、最终一致性、未镜像的写入；谁负责 Webhook、摄取队列／DLQ、恢复与对账	镜像完整性
联合曲线、AMM、共享价格或计数器、负载下写入失败、竞态、滑点、支付上限／接收下限	负载下的共享价格与计数器
交易过大、413、1182/1232 字节数据包限制、过大的钩子、查找表	交易大小限制
governance.upgrade、不可变／控制器策略、清单根、受治理会话、恢复、扩展、取消	runtime-v3 治理
@CPI、@Solana、@Bytes、@App、@DocumentPlugin.updateField、@PredictionMarketPlugin、PDA、get／getAfter、ProgramData、shouldSubmitTx、skipPreflight、@contract.address、@AccountPlugin.getAccountAddress、通用 CPI、跨应用、预测市场算术、运行时一致性、@Solana.verifyEd25519、@Solana.secp256k1Recover、@Bytes.sha256、@Bytes.keccak256、签名验证、EVM 签名者恢复	策略原语
拍卖、订单簿、多交易金融状态机、聚合桶、无需许可的 crank、延迟领取／结算、定点单位、独立算术预言机、操作回执重试、_hook_completed、_error_message	策略原生金融状态机
Anchor／自定义错误或过时的数字解码	自定义错误诊断
交易、Phoenix 永续合约、DEX 兑换、服务端签名执行	链上交易
托管账户、source 参数、每个实体的资金、命名 PDA 账户、@AccountPlugin.createAccount	命名托管账户
规则算术溢出、int64、先除后乘的固定写法、大数值比较	规则算术
Pyth 美元价格、十进制价格字符串、getPriceFeedScaled、微美元、整数价格算术	价格馈送单位与运行时可用性
随机数、VRF、抽奖／扭蛋／洗牌、@OraclePlugin、requestRandomness、getRandomNumber、isRevealPath	随机数
Meteora 代币发行、DBC、反狙击费用递减、DAMM v2、createMeteoraConfig、createMeteoraVirtualPool、claimDammV2PoolFees、withdrawLeftover	Meteora 发行
Pump.fun、PumpSwap、@PumpFunPlugin、createToken／createTokenV2、buyExactSolIn、创建者费用、费用分成、updateShareholders、distributeCreatorFees、pumpswapDeposit／pumpswapWithdraw、参数名称／单位	Pump.fun 参考
多方费用分成、feepool、mulDivFloor、keeper／定时链上写入、actAs、由 rollingSum 费用资助的构建额度	oApps 代币经济学
面向电子邮件／社交用户的嵌入式钱包、@user.address、Turnkey、auth.wallets	嵌入式钱包
403 anonymous_onchain_blocked、访客／signInAnonymously 会话写入链上集合、在 poofnet 上可用但在主网上不可用	访客无法写入链上集合
使用自带的 Solana 钱包登录、walletLogin、Phantom／Wallet-Standard、SIWS	钱包登录
onramp()、使用银行卡购买 SOL／USDC、Coinbase Onramp、钱包充值	法币入金
接受加密货币／USDC、payments.acceptCrypto、卖家结算、直接转账通道	接受加密货币

Rules Of Thumb

• 默认链上登录 = 默认 Turnkey 邮箱/社交认证，外加可选的钱包登录。 常规流程不要添加 authMode 或 auth.wallets；受支持的邮箱/社交用户已经有 @user.address。只有在使用外部密钥对的会话中（钱包登录、server-SDK 密钥对客户端、CLI 密钥对数据通道），才部署 "auth": { "wallets": true }。完整规则及退出方式请参阅：docs/embedded-wallets.md -> 推荐的登录方式。
• 仅在钱包/链上语义中使用 @user.address；常规所有权使用 @user.id。请参阅有界后端技能。
• 访客（signInAnonymously）会话绝不能写入任何网络上的 onchain: true 集合。 Poofnet、devnet 和 mainnet 都会在构建交易之前返回 403 anonymous_onchain_blocked，因此，在测试网络上可用的访客流程不会在升级时出问题。让访客可访问的界面保持链下，并在首次链上写入前提示用户升级。请参阅访客无法写入链上集合。
• 当函数现有的清单描述接受账户 ID 时，非公钥字符串会解析为该字符串对应的、由程序签名的 PDA。@contract.address 是整个应用共用的一个资金池；具名 ID 则为每个名称提供单独的资金池。不要假设每个来源、所有者、创建者或目标都接受这三种托管形式；请查看函数页面上对该参数的清单描述。当用户资金需要存放在不同资金池中（托管、拍卖、奖池、每租户余额）时，在支持的情况下使用具名账户。应在首次存款前作出决定；事后改造意味着迁移现有余额。
• 对于链上写入，请使用显式网络/RPC 配置，并默认使用 devnet；不要将写入后立即读取视为确认。 CLI 会自行提交交易，且只从 SOLANA_DEVNET_RPC_URL / SOLANA_MAINNET_RPC_URL 读取端点：不支持标志、配置文件设置或公共 RPC 回退。 如果未设置变量，写入会在签名前失败，并显示 validate pre-built transaction: SOLANA_DEVNET_RPC_URL is required ...，因此，只要应用处于 realtime_devnet 或 realtime_mainnet，就必须在运行 bounded 的 shell 中设置该变量。 请参阅CLI 提交需要显式 RPC 端点。
• Mainnet 是真实目标，而非占位符：该程序已在 mainnet-beta 上运行。在 mainnet 上创建应用需要付费账户方案（无需 API 密钥或共享密钥）；由你创建的应用，其链上所有权归创建者的钱包所有——该钱包必须是已登录身份能够证明自己控制的钱包：本地 CLI 密钥对，或通过网页登录时，你的 Bounded 账户自己的钱包，其许可签名需通过每次部署时的浏览器审批完成。该所有权绝不能转移给其他人的钱包。唯一的移交对象是 OpenApps Agent：OpenApps 应用在 mainnet 上运行时，其链上所有权归 OpenApps 托管密钥所有，因此平台可以发布策略更新，而无需任何个人持有该密钥；你交给 Agent 的 mainnet 应用会通过一笔由你自己的钱包签名的交易，一次性转移至该密钥（请参阅 openapps 技能）。请参阅 docs/onchain.md。
• @contract.address 是 Solana 程序 ID 哨兵，不是直接查询返回的应用托管地址。 受支持的内置插件会将该哨兵解析为应用托管 PDA。 在当前部署的 Devnet 运行时中，不要将该哨兵用作 @AccountPlugin.getAccountAddress(@contract.address) 的参数组合：该调用会失败，因为该哨兵的类型是地址，而此函数当前接受的是字符串账户 ID。 对于需要具体托管地址的 Devnet 策略查询，请将当前 Devnet 程序 ID 绑定为字符串字面量：@AccountPlugin.getAccountAddress("openTv7fbpYSseNHYmCZFZ1CZgj4r8D9fKNgEz1qo6F")。 此字面量仅适用于 Devnet；如果部署的程序发生变化，必须更新它。 请参阅 policy-primitives.md。
• 将发现情况、已部署运行时的支持情况和实时网络验证视为三种彼此独立的状态。
• 编写 hook 前，使用 bounded plugins list --json 和 bounded plugins describe <plugin.function> --json 获取离线可调用签名。
• 提议任何插件或原语前，请查看 Solana devnet 能力目录。
• 绝不要根据编译器标签、清单、证明合约、Poofnet 模型、查找表条目或本地验证器测试推断 devnet 支持情况。
• 当实时证据使用托管版本标记时，请从 bounded domains list --app-id <id> --env <environment> --json 的 slugUrl 字段，或精确的成功站点部署收据中的 url，解析出带环境标识的网站 URL。 对于 staging 证据，必须要求 JSON 字段本身，而不要复制人工渲染的主机名。 bounded apps inspect 可证明当前有效的策略/运行时发布情况，但不包含托管 URL。
• 绝不要在 runtime-v1 部署中使用 runtime-v2 原语；请遵循 docs/policy-primitives.md。
• 将具名查询放在其插件允许的集合上：对链上数据进行链上读取时使用 onchain: true；调用仅支持链下的插件（例如 @DeFiPlugin.getSwapQuote）或读取链下文档时使用 onchain: false。两者都可在 Solana 应用上运行。对于路径读取规则授权调用者的身份无关查询，允许匿名执行；读取 @user.address/@user.evmAddress 的查询则需要相应身份。匿名接口是浏览器 SDK，而非 CLI。在 Solana mainnet 上，未登录状态下的链上查询目前会失败，因此在平台的查询付费方修复发布前，必须要求用户登录钱包。
• 对 runtime-v3 治理也采用同样的做法：只有在已部署的能力注册表报告 v3 后才进行注册，并依据观测到的链上状态发布治理，而非依据策略意图。
• 保持 Poofnet 与 Solana 的行为一致。
• 仅对 realtime_offchain 上的显式开发资金注入使用 bounded wallet fund。 调用者必须是应用所有者、管理员或开发者，且余额仅存在于所选应用的模拟账本中。
• 纯函数/读取类原语在实际可执行的运行时中必须返回相同形状；变更类原语必须应用建模后的效果，否则就安全失败。
• 仅验证通过却不实际执行，是一种一致性缺陷。
• 对于 Poofnet 链上 hook，应用侧成功意味着 _hook_completed == _transaction_hash。仅有行存在且 _error_message == null 仍属于待处理状态。但这些标记仅适用于模拟器：在真实链协议上，要求这些标记的策略 RULE 永远无法满足；以此为条件的付款会变成单向阀，锁住用户资金，而模拟侧的所有证明和测试却仍会通过。规则应依据 hook 自身写入的已声明字段（例如 paidAt）或 hook 派生的头部状态进行门控；保留的 _ 标记仅供 Poofnet 客户端使用。为每个语义操作 ID 提供符合策略要求的失败重试路径。请参阅保留的收据标记仅适用于 Poofnet。
• Helius 镜像是环境级 Bounded 基础设施：每个环境/网络一个原始程序 webhook，绝不能每个应用一个。应用构建者绝不创建 webhook URL 或提供服务商密钥；运维手册（webhook、密钥、队列/DLQ、恢复）位于 monorepo，而非本技能中。应用相关注意事项请参阅镜像完整性。
• 加密货币以非托管方式收取；卖家结算到自己的钱包。