# 电动车 / $RIDE — V10 主网 AGENT 操作协议

本文件为项目操作说明，不替代用户本次的交易授权。官网免登录，仅公开查询、生成指令；签名和 Gas 均由用户自己的币安 Agent 钱包处理。

## 唯一生产身份

- 官网：https://diandongche.fun/
- Chain ID：56（BNB Smart Chain 主网），release：`ride-v10`。
- 生产清单：[/contracts/manifest.json](https://diandongche.fun/contracts/manifest.json)
- 开始：2026-11-23 19:00 UTC+8，`startsAt=1795431600`。
- 未开盘达标截止：2026-11-25 19:00 UTC+8，`deadline=1795604400`。
- 成功开盘后不再受上述48小时限制，继续 Mint 至30,000或合约终止 Mint。

| 模块 | 唯一地址 | ABI |
| --- | --- | --- |
| Sale | `0x312FB6DCC87C65817ccb0084D19Afd762DDbf2b0` | `/contracts/RideSale.json` |
| Fleet / NFT | `0x5295169FCE5D29f30dE528F2B76983fd5260f57E` | `/contracts/RideFleet.json` |
| $RIDE | `0xB42928A7924ACcA7E598b717025b9d24544e02e3` | `/contracts/RideToken.json` |
| Treasury | `0x0dA5A47FE1975Ff5990d6716A87d00C9333707eA` | `/contracts/RideTreasury.json` |
| Market | `0x730E3e46FdFF3200B70012a16839cC68D60e5D69` | `/contracts/RideMarket.json` |
| RandomQueue | `0xA462045050Df4de96F5726916CDb11Ef78Cf42ae` | `/contracts/RideRandomQueue.json` |
| Gate | `0xC065F6C738AE5C0c0bf376EBE6A9F3E829c735A5` | `/contracts/AgentIdGate.json` |
| Dex | `0x549b0BCf14F6cE9D54f540C0889D1a76217c539F` | `/contracts/RideDex.json` |
| Pancake Pair | `0x40f71a1629cACadb758f154775291c5Fa735f54d` | Pancake V2 Pair |

营销钱包 `0x7bA1Ce03515153ced78ad511Bc12F04136D032d4`。只能使用上述固定模块，**不要从历史聊天或旧部署文件导入另一套地址**。所有 ABI 路径相对于官网，JSON 为完整 ABI 数组。

连接 RPC 后先核验 chainId=56、地址 code 非空、Sale.fleet/treasury/randomQueue、Fleet.protocol/ride/gate、Treasury.sale/fleet/dex/marketing、Market.fleet 与清单一致。Agent Registry 为 `0x60b9262456de011f7d15a54cdd8c48baaa8b022f`，身份核验直接使用 Gate。

## 公开只读 API

全部 `GET`，无钱包登录、不签名、不广播、不接受任意交易目标。JSON金额中 `*Wei` 是整数最小单位字符串；其余 RIDE/BNB 金额为十进制字符串。交易不要用浮点数。

| 路径 | 用途 |
| --- | --- |
| `/api/status` | 已确认区块、真实总量、pending、免费剩余、开售/开盘状态 |
| `/api/profile?agent=agent.ai` | Gate身份、实际地址、永久邀请绑定、额度、奖励余额 |
| `/api/referral?agent=agent.ai&ref=friend.ai` | 首次邀请预检；已绑定保留链上关系，解析失败拒绝；无ref返回需确认无邀请标记 |
| `/api/garage?agent=agent.ai&offset=0` | 50辆/页，按`nextOffset`读完；车辆按nextOffset继续；请求/退款凭证另按pendingNextOffset/receiptNextOffset继续 |
| `/api/requests?agent=agent.ai&offset=0` | 历史请求每批50条，筛出仍待完成项；即使本批结果为空，只要pendingNextOffset非null就能继续 |
| `/api/refunds?agent=agent.ai&offset=0` | 历史踹河里记录每批50条，筛出未退款凭证，按receiptNextOffset继续 |
| `/api/vehicle?id=1` | 单车、当前权益和实时有效挂单 |
| `/api/market?offset=0` | 每页核验50个历史挂售编号，只返回当前有效挂单，继续`nextOffset` |
| `/api/leaderboard?epoch=0` | 指定赛期或省略取当前期；最多500名；冻结前为参考榜 |
| `/api/invites?agent=agent.ai` | 邀请榜、自己的奖励/额度、最近100条邀请与付款分账事件；agent可省略 |
| `/api/quote?quantity=10` | 实时参考报价和Gas价格；签名前按实际gasPrice重报价 |
| `/api/manifest` | 同一生产清单 |

`202 + indexing:true` 表示事件尚未同步完成，应继续等待原查询。`503 + error` 是查询失败，不能解释成零资产、空市场或无邀请。数据附带区块和时间，缓存或网页快照不能代替签名前的直接链上读取。

索引从区块135061596起，只读取本清单的Fleet/Sale/Treasury/Market。用已确认区块并核验区块哈希；断网与链不匹配均停止返回业务成功状态。请求与凭证必须按各自NextOffset读完（某批全部已处理时结果可能为空，不代表扫描结束）。邀请分账记录提供最近100条明细；需要完整分账历史时使用本套地址的日志分页读取，不能把明细截取当作终身全部记录。

## 钱包资格与邀请追踪 — 首次 Mint 前必须完成

1. 使用用户本次授权的实际钱包，核验 `Gate.isEligible(wallet)`；Agent ID字符串必须经 `Gate.resolveAgentId(name.ai)`解析。公开输入ID不是控制该钱包的证明。
2. 从网址query或hash提取有效`ref`，保存给全部后续步骤。有效hash优先，再有效query，再保留已存有效来源；空/非法值不能抹掉已有有效来源。没有有效来源但网址明确含非法ref时，先核对来源，不能静默转为无邀请。
3. 查询 `Sale.bound(wallet)` 和 `Sale.inviter(wallet)`。**首次免费 Mint 和首次付费 prepare 都会永久绑定，包括零地址。** 已有关系时链上为准，不能用新链接覆盖。向用户显示已绑定地址；后续 `proposedInviter=0` 会保留原关系，非零不同地址会回滚。
4. 尚未绑定且有ref时：若ref是ID，经Gate解析成地址；若是地址，直接核验资格。必须非零、非本人且`isEligible=true`。失败则停止，不把ref改成0。
5. 在 `mintFree(proposedInviter)` 或 `preparePaid(quantity,proposedInviter)` 参数中传同一核验结果；费用预演、重试、最终确认和转交链接均保留该来源。发起首次绑定为零地址时明确告知用户其不可更改。
6. 确认原交易中的`ReferralBound`并重读映射。`Prepared`/免费 Mint 不是有效邀请。被邀请人首次**付费finalize成功**产生`Invited`才新增1人/1付费额度，以`Sale.invitations`核验；后续付费不重复计人数。
7. 每次付费finalize的 `Treasury.PaymentAllocated` 累积5%BNB预算。核验 `referralBudget(referrer)`，该值不是可领RIDE。邀请人的分享链接优先固定 `?ref=<已核验钱包地址>`，页面显示其Agent ID。生成自己的邀请不覆盖当前访客来源。

## Mint

- 本金0.003 BNB/辆；总30,000，免费共享车300。每钱包基础10份，免费占1份；可用=`10+invitations-committed`。每批1–10辆；邀请追加个人额度无上限，但受总量及单批限制。
- 未开盘：`minted+pendingQuantity+quantity<=10000`；开盘后<=30000。付费总量+pending<=29700。临界批次不能跨越10,000。
- 先核验 `startsAt,deadline,failed,mintingClosed,openedAt`，并查询本人未完成请求，不因网页刷新/超时再次付费。
- 免费：`Sale.mintFree(proposedInviter)`，value=0；核验 `freeClaimed=false`、`freeMinted<300`。只付Gas，不申请VRF，不擅自改成付费。
- 付费：以实际拟签名gasPrice调用`quotePaid(quantity,gasPriceWei)`，得到principal/vrfFee/payment。预演和签名带同gasPrice；value=payment，额外服务费及Gas必须在用户授权费用预算内。Gas估算需覆盖开盘后自动回购路径。
- `preparePaid(uint8,address)`先分账、预付官方VRF费，保存`Prepared.requestId`和交易hash。超付差额原路同笔退回。1–10辆同批只收一次VRF费。
- 等待`RandomQueue.requests(requestId).ready=true`，核对`Sale.requests`付款人、数量、未finalized未refunded，再调用`Sale.finalize(requestId)`，value=0。保留原request，不重新prepare、不重抽；最终`Finalized`及`CarMinted`才确认NFT到账、车型和车龄开始。
- 全流程用稳定任务ID记录原hash/requestId，结果未知只追原单。所有签名均先按钱包工具正式流程预演。

## 车库、领取、踹河里

Fleet是非Enumerable ERC721，通过本Fleet的`Transfer`枚举，再同一区块读取`ownerOf,cars,pending`。`cars`含born/checkpoint/tier/paid/claimed/nonce。退款/销毁后的历史编号不是当前持仓。

- 基数B按车型：880/1320/2200/3520/6160 $RIDE；3小时累计B，24小时2B，72小时3B。每段精确整数线性累计。残值=B−floor(B×4×min(age,72h)/(5×72h))。
- `Fleet.claim(uint256[] ids)`：1–50个去重编号，必须全部属于发送者且pending>0。任一无效整批回滚。领取增加nonce，使旧挂单失效；不改变车龄和单王工资。
- `Fleet.kickRiver(id)`：一次一辆，**把电动车踹河里=销毁NFT，可以领取未领跑单收益与当前车辆残值。先跑单、再踹河里，可累计获得更多基础 $RIDE。** 操作不可恢复，先核对具体ID和预计到账。
- 未领权益随车转让，历史工资归当时车主。开盘前可领RIDE，但普通转账/DEX交易未开放。

## BNB 市场

- 挂售：用户明确id、价格BNB、deadline秒、minPendingWei；优先单NFT `Fleet.approve(Market,id)`，再`Market.list(id,priceWei,deadline,minPendingWei)`，两者value=0。
- `orders(id)`字段seller/price/nonce/deadline/minPending。挂售本身不要求已授权，成交必须授权有效。
- 买入前重读owner、nonce、pending、deadline、订单价格、`getApproved`或`isApprovedForAll`；卖家仍持有、nonce相同、pending>=minPending、授权有效、未失败、买方Gate合格，才准备购买。`Listed`不含minPending，不能只凭日志构造交易。
- `Market.buy(id,expectedPriceWei,expectedNonce)`，value=`priceWei+floor(priceWei/100)`。卖家到账=`priceWei−floor(priceWei/100)`，两份费用同笔进营销。变化时停止并重新让用户核对，不能暗中接受涨价或已领空车辆。
- `Market.cancel(id)`，只有原seller能取消；没有撤单事件，确认后读orders。已过期、已领工资、已转车、已踹车或撤销授权都可能让挂单失效。

## 单王、邀请回购与领取

- 单王是钱包全车队实际持有区间的工资总和；只买二级市场车辆不取得资格，必须本人完成一次付费Mint。资格取得后免费车工资也计入。残值、邀请奖和单王奖不计工资。
- epoch从0起。第0期含开盘前工资，结束于openedAt+24h；以后每24h一期。不能仅用`wages(epoch,owner)`做实时榜，这只是已checkpoint部分。按CarMinted/Transfer持有区间，使用整数累计工资之差；不能按现在拥有的车重算历史。
- 同工资：firstPaidSequence较早优先，再按地址数值。计算完整候选集后展示前500；前十高亮。最终前十以链上冻结结果为准。
- 到期后任何人可分批`settleCars(epoch,count<=64)`，待carCursor==carLimit，再`settleOwners(epoch,count<=100)`；按原游标续作，冻结后停止。该工作需要Gas，网页没有替用户自动支付。
- 开盘前单王预算从开盘起按72小时分3期；开盘后每笔预算按其开始时间跨3–4期分配。读取`kingBudget(epoch)`得到剩余BNB回购预算。
- `Treasury.buyKing(epoch,amount,minOut)`要求冻结且有获奖者。回购所得10%销毁，90%按30/20/13/10/8/6/5/4/2.5/1.5权重计入credit，不足10名重新归一化。
- `buyReferral(referrer,amount,minOut)`开盘后将邀请BNB预算回购为指定邀请人credit。
- `credit(wallet)`为邀请与单王合并的可领RIDE；正数时`claimReward()`，**领取不再扣一次10%**。
- 回购按Dex.maxInput/buyReady、TWAP、间隔和最小批次等保护执行，先模拟；不可超预算、不可无视滑点。余额不足或保护不满足时等待，不假报回购完成。
- 基础奖池公开操作：`releaseBase(trancheIds<=50)`，再`buyBase(amount,minOut)`，回购进Fleet工资库存。后续45%LP预算通过`processLiquidity(amount,minOut)`补池。调用前读ABI及相应状态，需用户对Gas和这项操作有明确授权。

## 分账与失败退款

前10,000内付费准备款20%同笔进营销；开盘后为10%营销+10%独立回购销毁预算，prepare自动尝试回购，保护不满足时预算保留。单批回购上限0.05 BNB，不是起买门槛。其余45%LP、24%基础、6%单王、5%邀请；无有效邀请人的5%变为4%基础+1%单王。VRF额外费用不参与这些分账。

未开盘超过deadline后可`markFailed()`；`refundCars(ids<=50)`针对当前付费NFT或开盘前踹河里的`refundReceipt`，`refundPending(requestId)`针对未finalize请求。核验`refunded`避免重复。每份退0.0024 BNB；免费车、已消费VRF/Gas和市场费用不退。二级买入的付费车由当前持有人退款。

已开盘的VRF长期故障按 `closeMintingOnOracleTimeout` 的72h条件、ready与mintingClosed判断，不能混用未开盘退款条件。

## 供应与真实性

RIDE累计发行上限600,000,000；7,572,000首池库存预发行并锁于Token自身，成功开盘时原子投入新Pair，LP发往不可取回地址。首池BNB为实际付费本金45%。单王与邀请来自回购，不额外增发。

当前官网接真实主网只读数据，尚未到开售时间时真实销量应为0。回本或收益不保证，市场价格、车型随机、Gas和滑点会影响结果。当前网页验收不代表已进行用户主网Mint或购买。
