A blockchain micro-lottery, dismantled. 一份链上夺宝平台,拆开来看

A user opens the Telegram mini-app, deposits USDT on BSC (or BTC on Bitcoin), buys one or more 1-USDT seats in a round, and waits for the round to sell out. When it does, the platform draws a winner via a commit-reveal seed that anyone can verify locally — no gas, no Chainlink, no on-chain selection. Winnings settle to the platform balance ledger immediately; withdrawals are a separate, audited path with multi-sig custody on the cold-tier. 用户打开 Telegram 小程序,把 BSC 上的 USDT (或 Bitcoin 上的 BTC)充值进来,在某一轮里买一个或多个 1 USDT 号码, 等本轮售罄。售罄之后,平台用 commit-reveal 种子开奖,任何人都可以本地验证 —— 不消耗 gas、不依赖 Chainlink、不上链选号。奖金即时落到平台余额账本; 提现走独立、可审计的路径,冷钱包多签托管。

The product surface is small. The plumbing is the point: nine independent Spring Boot services, each with its own MySQL schema, talk over Feign (synchronous) and Kafka (asynchronous, at-least-once with consumer-side idempotency). Sign-service holds the private keys and signs blindly. Wallet-service is the only source of truth for balances. Chain-service is the only thing that talks to a node. Everyone else is forbidden from doing those things — by code, by review, and by boot validators that refuse to start a prod profile when a stub is still wired in.

These were settled before the architecture docs ran. Every later document honors them; reversing one is a re-architecture, not a refactor. 这四条早在架构文档启动之前就定下了。后续每一份文档都遵循它们; 反转任何一条都属于重新设计架构,不是重构。

A dozen modules live under duobao-backend/. Most are production-ready, a couple are partial (clearly demarcated), a couple are stub-only. The map below groups by tier — edge, money, chain, auxiliary. duobao-backend/ 下大约一打模块。大多数已生产就绪, 少数处于部分实现(明确标注),个别只有桩。下面的地图按层分组——边缘、资金、链路、辅助。

The product spec asks for three trust models, ranked by how much of the draw lives on-chain. v1.0 ships only the leftmost; the other two are present as interface implementations with stub bodies so a future flip is a config change, not a rewrite. 产品规格要求三种信任模型,按"开奖逻辑落在链上的比例"排序。 v1.0 只上线最左边那个;另外两个以接口 + 桩体的方式存在, 未来切换是改一行配置,不是重写代码。

// duobao-api · the single contract every mode honors
public interface DrawEngine {
    DrawResult draw(DrawContext ctx);   // initiate
    DrawMode   supportedMode();
    default boolean supportsAsyncCallback() { return false; }
}

// game-service · wiring
@Bean
@ConditionalOnProperty(name = "one.draw.mode", havingValue = "BACKEND")
DrawEngine backendEngine(...) { return new BackendCommitRevealEngine(...); }

Every chain interaction goes through a single ChainAdapter interface. A new chain is one adapter + one Nacos config block. Business code doesn't know if it's talking to BSC or Bitcoin. 所有链上交互走单一 ChainAdapter 接口。 新增一条链 = 一个 adapter + 一段 Nacos 配置。业务代码完全不知道自己在跟 BSC 还是 Bitcoin 说话。

public interface ChainAdapter {
    ExecutionChain executionChain();
    boolean   isAddressValid(String address);
    BigInteger getBalance(String address, String token);
    List<ChainEvent> scanBlock(long fromBlock, long toBlock);
    String     broadcastSignedTx(byte[] signedTx);
    Optional<TxReceipt> getReceipt(String txHash);
    int        requiredConfirmations();
}

Dialect comparison

Smart contracts

Three UUPS proxies under duobao-contracts/, all owned by a Gnosis Safe 3-of-5 wired through a 24-hour Timelock. No upgrade can sneak through; any single signer can cancel mid-window.

Twelve isolated schemas, no cross-service joins. Consistency rides on Kafka topics with at-least-once delivery and consumer-side idempotency keyed on ref_id. Three retries then DLQ + alert. 十几个互相隔离的 schema,不允许跨服务 join。一致性靠 Kafka topic 的至少一次投递 + 消费侧用 ref_id 做幂等。重试 3 次后进 DLQ 并告警。

Four pillars: KMS custody, JWT with revocation, idempotency at every money seam, and a service-to-service auth model that assumes the internal network is hostile. 四根支柱:KMS 私钥托管、可吊销的 JWT、 每一处资金接缝的幂等、以及"假设内网就是敌对的"的服务间认证模型。

Four environments, six chain enums, fully orthogonal. Nacos is the config plane, AWS Multi-AZ + MSK is the data plane, Prometheus + business-metric dashboards are the observability plane.

Environment matrix

Config plane (Nacos, three tiers)

Observability

Honest matrix. Anything stub returns a safe default (501, empty list, log to stdout); a boot validator refuses prod profile when a stub flag is set. Anything partial works for the core path but has a documented seam. 诚实矩阵。标 stub 的全部返回安全默认值 (501、空列表、写 stdout);启动期校验器在 stub 旗标还在的情况下拒绝以 prod profile 启动。 标 partial 的对核心路径可用,但有明确文档化的缝隙。

Top-5 deferred items by impact

Ten observations a senior engineer is likely to find non-obvious or unusually disciplined for a project at this stage. Order is rough; weight your own. 十条观察,资深工程师在这个阶段大概率会觉得"不显然"或"对这个阶段的项目而言异常自律"。 顺序是大致的,自行赋权。