区块链主币与代币这七个字，在需求文档里通常只占一行，落到代码里却是两条完全不同的处理路径。过去几年我参与过几套资产记账与归集系统的对接，最常返工的地方不是业务逻辑，而是有人把“主币”和“代币”当成同一种东西处理——用同一套余额查询接口、同一套转账封装、同一套对账字段，结果上线第一周就出现余额对不上、转账“成功”却没到账、精度差了好几个数量级的问题。这篇内容就把这件事从头拆一遍：主币和代币在账本层、合约层、索引层分别是什么形态，手续费为什么绕不开主币，代币标准接口为什么要那样设计，以及从零部署一枚测试代币、跑通转账与事件对账的完整步骤。适合刚接触链上开发的后端同学、做资产对账与数据统计的同学，也适合想搞清楚“为什么我转了币对方没收到”的普通使用者参考。不需要你懂密码学，只要会写一点后端代码、能看懂函数签名，就能跟着走完。

1. 先把概念摆正：主币和代币到底差在哪一层

1.1 从一次对账事故说起：地址余额为什么对不上

早些时候我接手过一个内部记账模块的排查。现象很典型：某地址在主网浏览器上显示有一笔资产，但系统里查出来的余额是零。开发同学的第一反应是节点不同步，换了三个节点、重启了两次服务，数字还是零。最后发现问题特别朴素——他查的是主币余额接口，而那个地址上放的是合约代币，两者根本不是同一份数据。

这件事说明一个基本事实：主币余额和代币余额在链上是分开存储的。主币余额属于账户状态的一部分，节点自己就能算出来，你调一个余额查询接口，节点直接返回；代币余额则存在某个合约的内部状态里，节点并不知道“这是谁的余额”，它只能帮你把调用请求转发给合约，由合约执行一次读取函数再把结果返回。前者是“查账本”，后者是“问合约”，动作看着像，底层路径完全不同。

很多人把这件事理解成“主币是官方的，代币是民间的”，这个说法不算错，但太模糊，容易让人以为只是发行主体的差别。真正要命的是技术形态的差别：主币没有合约地址，代币一定有；主币的转账是协议内置的一种交易类型，代币的转账只是一次普通的合约函数调用；主币的精度由协议写死，代币的精度由合约作者自己声明。这三条差异直接决定了你的代码要写几套分支。

还有一个更隐蔽的坑：同一条链上，主币和代币共用同一个地址。你的账户地址既是主币的持有凭证，也是代币的持有凭证，但它们之间没有任何兑换关系，也不会互相影响。地址里有主币，不代表有代币；地址里有代币，也不代表付得起手续费。这个“共用地址但不共用余额”的特性，是后面绝大多数误解的源头。

1.2 三层视角看资产：账本层、合约层、索引层

我习惯把链上资产拆成三层来看，这样排查问题时能快速定位到底哪一层出了偏差。

第一层是账本层，也就是链本身的账户状态。主币就活在这一层。它由协议规则维护，转账时会校验签名、扣减发送方余额、增加接收方余额，整个过程不需要执行任何用户代码，因此成本低、行为可预测。你在这一层能拿到的东西很有限：地址、余额、交易序号（nonce），仅此而已。

第二层是合约层。代币活在这里。合约本质上是一段部署在链上的程序，它的内部有一张映射表，记录“哪个地址对应多少数量”。转账就是调用这张表的写入函数，同时触发一条事件日志。合约层的能力比账本层丰富得多，可以增发、销毁、冻结、设置税率、做黑白名单，但也意味着行为完全取决于代码怎么写——代码里写错了，链上不会有任何机制替你兜底。

第三层是索引层，也就是我们这些做业务系统的人自己搭的那一层。链上数据是线性的、只追加的，但业务查询需要“按地址查所有转账记录”“按时间聚合流入流出”，这些直接问节点会非常慢甚至问不出来。所以通常要把区块和日志扫下来，落到数据库里做二次组织。索引层最容易出错，因为它同时依赖前两层的数据，任何一层的理解偏差都会在这里放大成对账错误。

把这三层分清之后，很多问题就有了明确的归属。余额查不到，先问是查账本还是问合约；转账没到账，先看是交易没上链，还是上链了但调用的是错误的函数；记录漏了，先看扫描的起始块和过滤条件对不对。

1.3 一张表看清主币与代币的核心差异

下面这张表是我自己在做方案评审时常用的对照，基本上把两边的差异压缩到了一页里。实际写代码时，凡是表里出现差异的行，都意味着代码里需要一条独立分支。

表格里最容易被忽略的是最后两行。主币转账失败，整笔交易作废，余额不会动；代币转账如果合约写得不够严谨，比如先扣了发送方余额、再调用接收方的一个回调函数、回调里又抛了异常，那么回滚范围取决于代码结构，写得不好就会出现中间态。至于误转，主币转到任意地址都算“有效地址”，而代币如果转到一个不支持该标准的合约地址，资产可能永久取不出来。这两点在后面的排查章节还会展开。

2. 技术底座拆解：账户模型、手续费与状态存储

2.1 账户模型与 UTXO 模型：余额到底记在谁头上

链上记账有两种主流模型，理解它们的差别，能帮你明白为什么有些链的主币查询接口长得完全不一样。

账户模型像银行卡。每个地址在链上有一个状态对象，里面存着余额、交易序号等字段。转账就是把 A 的余额减掉、B 的余额加上，一步到位。这种模型的好处是查询简单：给我一个地址，我直接读状态就能得到余额，复杂度是常数级。代币基本都建立在账户模型之上，因为映射表天然就是“地址到数量”的对应关系。

UTXO 模型像现金。链上不存在“余额”这个字段，存在的是一堆“未花费的输出”，每一笔都是“某地址收到多少钱”的凭证。你要知道余额，得把这地址名下所有还没花掉的凭证加起来。转账时不是改余额，而是把旧凭证作废、生成新凭证。这种模型在并发处理和隐私上有优势，但对业务系统很不友好——你没法直接查余额，得自己维护一份汇总。

我在实际项目里踩过的坑是：团队先做了账户模型的链，后来要接一条 UTXO 模型的链，结果发现整个余额模块要从“读字段”改成“扫全量输出再聚合”，工作量远超预期。所以选型阶段一定要先确认目标链用哪种模型，别等代码写完才发现余额查询接口对不上。

还有一个细节：UTXO 模型下没有 nonce 的概念，防重放靠的是输入引用，交易顺序也不像账户模型那样严格。如果你的业务逻辑依赖“同一地址的交易必须按顺序处理”，在 UTXO 链上就需要额外做排序，否则会出现“后发的交易先确认”的情况。

2.2 手续费为什么必须用主币付

这是新手最容易卡住的地方：手里明明有一堆代币，为什么一笔都转不出去？答案是手续费只能用主币支付。

原因在于资源计量。链上每一笔交易都要占用区块空间和计算资源，节点需要一套机制防止有人无限刷交易。最直接的办法就是让交易发起方付出一点主币成本。这个成本在交易被打包前就要扣除，而扣款动作发生在账本层——那时候合约还没开始执行，链根本不知道你手里有什么代币，也不可能拿代币来抵扣。

所以代币转账的真实成本结构是“两笔”：一笔是主币手续费，付给网络；另一笔是合约内部的数量变更，纯粹是状态写入，不产生额外费用（除非合约自己设计了收费逻辑）。这也解释了一个常见现象：某地址的代币余额很大，但主币余额为零，那么这个地址实际上是“冻结”状态，什么都做不了。

注意：给地址打主币时不要卡着最小值打。手续费会随网络拥堵波动，打得太精确，遇上高峰就连一笔都发不出去，反而要再做一次补币操作。

工程上我一般会留一个“手续费水位”监控：对每个需要发起交易的业务地址，定期检查主币余额，低于阈值就触发补充。阈值不要设成固定值，按最近若干区块的平均手续费乘以预估交易数再乘一个安全系数来算，比拍脑袋定一个数字靠谱得多。

有些场景会用到“代付”思路：让第三方地址替用户付手续费，用户只签名不付钱。这在技术上是可行的，实现方式通常是用户签一笔离链消息，第三方把它包装成自己的交易提交。但这套机制会引入额外的信任和密钥管理问题，非必要不建议一上来就做。

2.3 状态存储与精度：小数位、整型与溢出

链上没有浮点数。所有余额都是整数，所谓“小数位”只是一个显示约定。

以常见的 18 位精度为例，链上存的是最小单位，1 个显示单位等于 10 的 18 次方个最小单位。合约里声明的小数位只影响前端怎么展示，不影响运算。这意味着两件事：第一，你在数据库里存余额时也必须存整数，别用浮点类型，否则大数会丢精度；第二，做加减乘除时要注意单位统一，任何时候都要先确认手上的数字是“显示单位”还是“最小单位”。

我见过最典型的事故是前端直接把链上返回的整数除以 100 显示，因为“看起来像分”。结果一笔本该显示 1.00 的金额显示成了 0.01，对账系统直接炸掉。正确做法是读出合约声明的小数位，动态计算除数，不要硬编码。

溢出是另一个必须考虑的点。整数类型有上限，如果总量乘以精度之后超过上限，部署时就会直接失败；如果是运行时的乘法，则可能回绕成一个极小的数字。写合约时要用带溢出检查的运算方式，或者在关键路径上做前置断言。做后端时同理，数据库字段的位数要按“总量 × 10^精度”来估算，别用默认的整型。

精度一旦部署就很难改。改精度意味着所有已存在的余额数值含义全部变化，等于把整个账本重写一遍。所以部署前一定要想清楚，宁可多留几位，也别事后后悔。

2.4 授权机制：为什么代币转账有“两步走”

主币转账是一步：签名、广播、到账。代币转账在很多时候是两步：先授权，再划转。

授权的作用是让某个地址能够动用你名下的代币，额度由你自己设定。合约里维护另一张映射表，记录“谁允许谁动用多少”。授权的典型场景是去中心化应用：你不想把私钥交给对方，但又需要对方在你确认后把钱划走，于是先给一个额度，对方在额度内发起划转。

这套机制很灵活，但风险也集中在这里。额度设得太大，等于把支配权长期敞开；额度设了但忘了收回，合约一旦出问题，损失上限就是你授权过的数量。我在审查代码时见过把授权额度直接设成“最大值”的写法，理由是“省得以后反复授权”——从用户体验看确实省事，从风险控制看是把自己所有的代币都押在了一个合约上。

注意：修改授权额度时，某些老标准要求先把额度改成零再设新值，否则会因为防止竞态的设计而失败。新一点的接口提供了“增加/减少额度”的方法，能绕开这个问题，但兼容性要自己确认。

从业务系统角度，授权状态也需要纳入对账范围。很多团队只对账余额，不对账授权额度，结果某天发现某个地址的额度被外部合约用掉了大半，却查不到是谁在什么时候用的。授权变更同样会触发事件日志，把它一起扫下来，账才算是完整的。

3. 代币标准与合约实现要点

3.1 同质化代币标准的最小接口

所谓“标准”，本质是一份函数签名约定。大家按同一套名字写函数，钱包和浏览器才能用同一套代码去适配不同的代币。同质化代币的最小接口通常包含这几个部分：查询总量、查询某地址余额、转账、授权、查询授权额度、基于授权划转、查询小数位、查询符号与名称。

这套接口看起来简单，但每一处都有讲究。比如转账函数要返回一个布尔值表示成功，可现实中大量合约在失败时直接抛异常而不是返回 false，导致调用方必须同时处理两种情况。再比如余额查询必须对不存在的地址返回零而不是报错，否则前端遍历地址列表时会到处崩。

下面是我常用的一个最小实现骨架，去掉了业务定制部分，只保留标准要求的行为。实际项目里我会在这个基础上加权限控制和事件，但结构不变。

// 仅示意标准接口的最小行为，非生产代码 contract SimpleToken { string public name = "Demo Token"; string public symbol = "DMO"; uint8 public decimals = 18; uint256 public totalSupply; mapping(address => uint256) public balanceOf; mapping(address => mapping(address => uint256)) public allowance; event Transfer(address indexed from, address indexed to, uint256 value); event Approval(address indexed owner, address indexed spender, uint256 value); constructor(uint256 initial) { totalSupply = initial; balanceOf[msg.sender] = initial; emit Transfer(address(0), msg.sender, initial); } function transfer(address to, uint256 value) external returns (bool) { require(balanceOf[msg.sender] >= value, "insufficient"); balanceOf[msg.sender] -= value; balanceOf[to] += value; emit Transfer(msg.sender, to, value); return true; } function approve(address spender, uint256 value) external returns (bool) { allowance[msg.sender][spender] = value; emit Approval(msg.sender, spender, value); return true; } function transferFrom(address from, address to, uint256 value) external returns (bool) { require(balanceOf[from] >= value, "insufficient"); require(allowance[from][msg.sender] >= value, "not allowed"); allowance[from][msg.sender] -= value; balanceOf[from] -= value; balanceOf[to] += value; emit Transfer(from, to, value); return true; } }

这段代码里最关键的不是加减法，而是两处细节：一是初始化时给零地址发了一条转账事件，这是约定俗成的做法，索引服务靠它识别“创世铸造”；二是扣减授权的顺序必须在余额扣减之前完成校验，否则会出现“余额够但额度不够”却已经改了状态的情况。虽然异常会整体回滚，但把校验集中在前、状态变更集中在后，是更安全的写法习惯。

3.2 增发、销毁与权限设计

标准接口只规定了“转账”，没规定“谁能造币”。所以任何一枚真实流通的代币，都要自己回答一个问题：总量是固定的，还是可以变的？

固定总量的实现最简单，构造函数里一次性写入，之后没有任何函数能改。这种设计的好处是规则透明，坏处是没法应对业务变化，比如需要给生态激励预留份额时就没有腾挪空间。

可变总量就需要引入权限。常见的做法是设一个管理员地址，只有它能调用增发和销毁函数。这里有个必须想清楚的边界：管理员权限是单点还是多点？是永久有效还是可以放弃？放弃之后还能不能恢复？

我参与过的一个模拟项目里，最初的实现是“部署者地址永久拥有增发权”。评审时有人提了一个问题：如果这个地址的密钥丢失，增发功能就永久失效；如果密钥泄露，任何人都能无限增发。最后改成了多地址共同确认加时间锁的方案，虽然复杂了一些，但至少不会因为一个人的失误把整个资产的规则毁掉。

销毁逻辑也有坑。有些实现只把发送方的余额减掉，却不减总量，导致总量和实际流通量对不上；有些实现把币打到零地址当作销毁，但零地址的余额又被算进了某些统计口径里。正确做法是：减余额、减总量、发一条转到零地址的事件，三件事一起做，索引层才有一致的判断依据。

3.3 事件日志：链上对账的唯一可信来源

做资产系统，最容易犯的错误是“拿交易状态当结果”。交易成功只说明这笔交易被区块打包且执行没有抛异常，不代表你的业务逻辑真的发生了。真正可靠的对账依据是事件日志。

事件日志是合约执行过程中主动写出的一段结构化数据，包含合约地址、若干索引字段（通常叫 topic）和一段数据体。标准代币的转账事件会把发送方、接收方作为索引字段，把数量作为数据体。索引服务的典型做法是：按合约地址和事件签名过滤日志，把命中的条目解析出来落库。

这套做法有三个必须注意的点。

第一是确认数。日志刚写进区块时并不算最终确定，链在极端情况下可能发生分叉回滚，那条日志就消失了。所以扫描时要留一段确认深度，只处理已经足够深的区块。深度取多少取决于链的出块速度和回滚概率，太快会导致数据反复，太慢会影响实时性。

第二是幂等。同一条日志可能被扫到多次，比如服务重启后从上一处断点重扫。落库时要用“交易哈希 + 日志序号”做唯一键，重复插入直接忽略，而不是靠时间戳或者自增主键去重。

第三是分页。节点对单次日志查询的区块范围通常有限制，一次查几万个区块很可能直接被拒。正确做法是按固定步长分段查询，记录每段的进度，失败重试时从断点继续，而不是从头再来。

3.4 调用与读取的差别：写操作和读操作的成本不对称

代币的“查询余额”和“转账”在接口上长得像，成本却差了几个数量级。

查询是只读调用，不发交易、不消耗手续费、不产生区块记录，节点在本地模拟执行一下就返回结果。它的限制是只能读，不能改。工程上适合做余额展示、额度校验、参数探测。

转账是写入调用，要签名、要广播、要等打包、要付手续费，还会永久留下记录。它的问题是慢且不可撤销，一旦发出去就没有“撤销”按钮。

我见过把两者混用的写法：在批量对账脚本里循环调用转账函数去“测试地址是否可用”，结果脚本跑了一晚上，手续费烧掉一大堆，链上还多了一堆无意义的转账记录。正确做法是用只读调用做探活，读一次余额或者读一次小数位，能返回就说明地址和合约都是通的。

还有一个小细节：只读调用可以指定“在某个历史区块上执行”。这在补数据时特别有用，比如你要还原某个时间点的余额快照，指定历史区块号就能拿到当时的数值，而不必依赖现在的状态。

4. 实操：从零发一枚测试代币并跑通对账

4.1 环境与工具准备

整套流程我只用三样东西：一条本地测试链、一个合约编译工具、一个脚本运行时。测试链跑在本机，出块快、不花钱、随便折腾；编译工具负责把源码编成字节码和接口描述；脚本负责部署、调用和解析结果。

本地链启动后通常会给你若干个预置账户，每个账户带足量的测试主币。这一步很重要——没有主币就付不了手续费，后面所有写操作都做不了。我一般会先确认账户列表和余额，把要用的那个地址单独记下来，避免后面在多个地址之间搞混。

# 启动本地测试链（示意，具体命令以所用工具为准） local-chain --port 8545 --accounts 10 --balance 1000 # 确认账户与余额 local-chain attach --exec "listAccounts()"

环境准备好之后，先在纸上把参数定下来：代币名称、符号、小数位、初始总量。小数位建议先用 18，跟主流习惯对齐；初始总量按“总量 × 10^18”算出最小单位数，确认它没有超出整数上限。这个计算别心算，写个小脚本跑一下，把结果打印出来贴在配置里。

4.2 部署脚本与参数计算

部署本质上是发一笔“创建合约”的交易，把编译后的字节码作为数据体发出去，链执行完后返回一个新地址。这个地址就是代币的合约地址，后面所有的查询和转账都要带上它。

我把部署过程写成脚本，参数从配置文件读，避免硬编码。脚本里做三件事：读配置、算最小单位总量、发部署交易并轮询结果。

// 部署脚本示意 const fs = require("fs"); const cfg = JSON.parse(fs.readFileSync("./token.config.json")); // 关键计算：显示总量换算成最小单位 const decimals = cfg.decimals; const rawSupply = BigInt(cfg.totalSupply) * (10n ** BigInt(decimals)); console.log("最小单位总量:", rawSupply.toString()); // 上限检查，整数上限约 1.15e77 const MAX = 2n ** 256n - 1n; if (rawSupply > MAX) throw new Error("总量超出整数上限"); async function deploy() { const factory = new ContractFactory(abi, bytecode, signer); const token = await factory.deploy(rawSupply); await token.deployed(); console.log("合约地址:", token.address); return token.address; }

这里有一个很容易被忽略的步骤：部署完成后，先做一次“回读校验”。读一下总量、小数位、符号，确认和配置一致。我遇到过配置里写 18 位、合约里写死 6 位的情况，原因是有一次手工改代码忘了同步配置，结果前端显示的金额差了 12 个数量级。回读校验的成本只有几秒钟，能省掉后面几小时的排查。

部署交易本身也要付手续费，所以部署账户必须有主币。如果部署失败，先看手续费够不够，再看字节码是不是编译失败留下的空值，最后看构造参数类型对不对。顺序别乱，从最简单的可能性查起。

4.3 转账、授权与划转的完整调用链

部署完之后，我一般会按“铸造 → 查询 → 直接转账 → 授权 → 代划转 → 再查询”的顺序跑一遍，每一步都打印前后余额。这样任何一环出问题，都能立刻定位。

第一步是确认初始余额落在部署账户上。读一次余额，应该等于初始总量。

第二步是直接转账，从部署账户转一小笔给另一个测试地址。转账前记下两边余额，转账后再读一次，检查差额是否等于转账数量、两边总和是否不变。这一步验证的是最基础的加减法。

第三步是授权。让部署账户给第三个地址授权一个额度，然后读授权额度确认写入成功。

第四步是代划转。用第三个地址发起划转，把部署账户的一部分代币转给第二个地址。这一步要验证两件事：目标地址余额增加，同时授权额度相应减少。

// 调用链示意 const before = await token.balanceOf(addrA); await token.transfer(addrB, amount); const after = await token.balanceOf(addrA); console.log("转出方减少:", (before - after).toString()); console.log("是否等于转账额:", (before - after) === amount); // 授权与划转 await token.approve(addrC, allowance); const left = await token.allowance(addrA, addrC); await token.connect(signerC).transferFrom(addrA, addrB, part); const leftAfter = await token.allowance(addrA, addrC); console.log("额度消耗:", (left - leftAfter).toString());

跑完这套流程，你会对“两步走”有非常直观的感受：直接转账只改两张表，代划转要改四张表（发送方余额、接收方余额、授权额度、总量不变）。这也解释了为什么代划转的失败原因比直接转账多得多——任何一张表的前置条件不满足，整笔都会失败。

注意：跑测试时不要用同一个地址既当发送方又当接收方。自己转给自己在账面上看不出变化，容易让人误以为“转账没生效”，白白浪费排查时间。

4.4 日志解析与余额校验的完整闭环

链上操作跑通只是第一步，真正决定系统可靠性的是“能不能从日志里还原出每一笔变动”。

我的做法是写一个扫描器，从部署区块开始，按固定步长往后扫，过滤出目标合约的转账事件，解析出发送方、接收方、数量，写入一张流水表。同时维护另一张余额表，每来一条流水就更新一次余额。最后拿余额表和合约里的实际余额做比对，差值必须为零。

// 日志扫描与余额更新示意 async function scan(fromBlock, toBlock) { const logs = await provider.getLogs({ address: tokenAddress, fromBlock, toBlock, topics: [TRANSFER_TOPIC] }); for (const log of logs) { const { from, to, value } = decodeTransfer(log); const key = `${log.transactionHash}-${log.logIndex}`; // 幂等写入 await db.raw(` INSERT INTO token_flow (uniq_key, from_addr, to_addr, amount, block_no) VALUES (?, ?, ?, ?, ?) ON CONFLICT (uniq_key) DO NOTHING `, [key, from, to, value.toString(), log.blockNumber]); } } // 对账：库内余额 vs 链上余额 async function reconcile(address) { const chainBal = await token.balanceOf(address); const dbBal = await db.one( "SELECT COALESCE(SUM(delta),0) AS v FROM balance_delta WHERE addr = ?", [address] ); return BigInt(dbBal.v) === BigInt(chainBal.toString()); }

对账脚本我建议做成定时任务，每天跑一次全量比对，每小时跑一次增量比对。全量比对会慢，但能发现历史数据被污染的问题；增量比对快，能及时发现新出现的偏差。两边都保留，比只做一种更稳妥。

还有一点，扫描器必须记录“已扫到哪个区块”。这个断点要落库，不能只放内存，否则服务一重启就得从头扫，区块多了根本扫不完。断点更新要和流水写入放在同一个事务里，避免出现“流水写了但断点没更新”导致重复扫描，或者“断点更新了但流水没写”导致漏数据。

5. 常见问题与排查技巧实录

5.1 转账显示成功但对方没收到

这是被问得最多的问题，原因通常落在四个方向。

第一个方向是链选错了。同一条私钥在不同链上对应同一个地址格式，但状态完全独立。在测试链上转的币，主网当然查不到。排查方法很简单：看交易哈希在哪条链上能查到，一查便知。

第二个方向是合约选错了。地址里有 A 代币，但你转的是 B 代币，或者转给了另一个同名合约。代币的“名称”是可以随便起的，两个不同合约可以叫同一个名字、用同一个符号，唯一可靠的区分方式是合约地址。所以流水表里必须存合约地址，不能只存符号。

第三个方向是把授权当成了转账。用户点了“授权”按钮，链上确实生成了一笔成功交易，但余额一分没动——因为授权只是开放额度，不划转资产。这个误解极其普遍，产品界面上最好把两者的文案区分得非常明显。

第四个方向是接收方是合约地址且不支持该标准。转过去之后余额确实记在了那个合约名下，但合约没有提供转出的函数，资产就卡住了。转账前先确认接收方是普通账户还是合约账户，如果是合约，要确认它实现了接收入账的逻辑。

5.2 余额显示为零或数量级明显不对

数量级错误几乎都出在精度上。链上返回的永远是最小单位整数，展示时必须除以 10 的小数位次方。硬编码除数是最常见的错误来源，尤其是从小数位不同的两枚代币之间复制代码时，很容易忘改。

另一种情况是查错了合约。有些代币存在“迁移”历史，旧合约还在链上、余额也还在，但已经不再流通。用户看到的是旧合约的数据，业务系统读的是新合约，两边自然对不上。

还有一种比较隐蔽：节点返回的是缓存数据。某些公共节点的读取接口有缓存策略，刚发生的交易可能查不到。这种情况换节点或者等几个区块再查就能确认，不必大动干戈改代码。

5.3 交易长时间不确认

交易发出去迟迟不上链，先看三件事：手续费给够没有、交易序号有没有冲突、发送方主币余额够不够付手续费。

手续费不足是最常见的。网络拥堵时，按旧价格估算的费用可能远低于实际打包门槛，交易就会一直排队。处理方式是重新发一笔相同序号、更高手续费的交易去覆盖，而不是傻等。

序号冲突则是并发场景的典型问题。同一地址同时发多笔交易，如果序号分配错了，后面的交易会因为“前一笔还没处理”而卡住。工程上的解决办法是给每个地址维护一个发送队列，串行分配序号，发完一笔确认一笔再发下一笔。

还有一种情况是交易本身在链上执行失败了，但因为手续费照扣，区块浏览器上仍然显示“已上链”。这时候要看执行状态字段，而不是只看有没有被打包。执行失败的原因可能是余额不足、授权不足、合约里主动抛了异常，具体要看失败时的返回数据。

5.4 日志漏抓与重复入账

索引层的问题排查起来最花时间，因为症状往往延迟出现：今天对账发现少了一笔，实际是三天前扫描器断了一次。

漏抓的常见原因有三个：起始区块设得太晚，把部署时的初始铸造事件漏掉了；事件签名算错，过滤条件永远匹配不上；单次查询的区块跨度过大，被节点截断返回。前两个改配置就能解决，第三个要改成分段扫描。

重复入账的原因通常只有一个：没有做幂等。服务重启、断点回退、人工补数据，都可能让同一条日志被处理两次。解决办法是给流水表加唯一键，用交易哈希加日志序号做联合唯一，写入时冲突即忽略。

注意：不要用“区块时间 + 金额 + 地址”做去重键。同一秒内同一对地址之间完全可能发生两笔金额相同的转账，这么去重会把真实流水误删。

我自己的经验是，索引服务上线前一定要做一次“断点演练”：手动停掉服务，改一下断点位置，重启后看它能不能正确补齐数据且不产生重复。这个演练能暴露绝大多数设计缺陷，成本却只有半小时。

5.5 一份可落地的排查清单

把上面这些整理成一张清单，遇到问题时从上往下过一遍，基本能覆盖八成以上的场景。

这张表我贴在过工位上，新人上手时按顺序走，比漫无目的地翻日志效率高得多。

6. 写在后面对接经验里的几句话

主币和代币的差异，说到底是一个“资产在哪一层”的问题。想清楚这一层，后面所有的接口设计、字段设计、对账逻辑都会变得顺理成章。我自己在做新链接入时，第一件事永远是画一张三层图，把主币、代币、索引分别标上去，再决定每个业务动作落在哪一层。

有个习惯我觉得挺值：每接一条新链，先手工发三笔交易——一笔主币转账、一笔代币直接转账、一笔代币授权加划转——然后把这三笔的日志、余额变化、手续费消耗全部记在本子上。这份手记看起来原始，但它是最可靠的行为基线，后面系统出了任何偏差，拿来一比就知道差在哪。

另外提醒一句，测试环境一定要和主环境隔离，包括合约地址、扫描断点、流水表。我见过测试数据混进生产库导致对账差异的事故，清理起来非常费劲。配置里给每条链、每个环境一个明确的标识，所有查询和写入都带上这个标识，能省掉很多麻烦。