UGE 开发者联调控制台

应用概览

保存凭证后点击「刷新」。

注册新应用（自助，无需联系运营方）

提交后立即返回 app_id 与 api_key。api_key 只显示这一次，关闭页面即无法找回（只能找运营方重置）。

应用名称 *（1-120 字符；app_id = SHA-256(名称)，同名注册会冲突）

业务描述 *（1-1000 字符）

qualified_actions *（至少勾一项）

PAID_ORDER QUALIFIED_ACTIVATION QUALIFIED_RETENTION VERIFIED_SERVICE

emitter 合约地址（发布链默认已预填）

证据保留天数（1-3650，默认 90）

技术联系人 *

安全联系人 *

Webhook

配置 / 修改回调地址

回调 URL（须 https；已配置过的情况下修改会轮换 signing_secret，旧密钥立即失效，需同步更新你服务端的验签密钥）

验签：x-uge-signature = HMAC-SHA256(signing_secret, 原始请求体)。signing_secret 仅在配置 webhook 时返回一次，控制台不展示历史值、不存储——请当场保存。

QBT 联调助手（emitter 路径）

填写业务参数 → 本地复算 family_id 与 proof_hash → 生成 reportQBT calldata；由你自己的 reporter 私钥在你的环境执行（控制台不收集私钥）。执行后 ≤10 分钟运营方 sync 结算并回调 webhook。

underlying_action_id（family 分组键，1-128 字节）

action_type

tier

subject（EVM 地址）

denom

gross（最小单位）

refund（最小单位，≤ gross）

订单证据 JSON（可选 — 用于本地生成 proof_hash = SHA-256(规范化 JSON)，键排序、无空白）

Family 查询

family_id（64 位 hex，可用 QBT 助手复算）

或按业务键计算：underlying_action_id（用连接区的 app_id 本地复算 family_id，无需手填）

PAV（可审计 Gas 权益账本）

epoch

requested_gas（可选）

Idempotency-Key（可选）

红线提醒：阶段 1/2 为「可审计的 Gas 权益账本」，不得表述为 Gas 抵扣 / 返还。

挑战 Attestation（MetaMask 签名 → 服务端中继上链）

挑战是 permissionless 动作：任何人在挑战窗口内可对一笔 attestation 提交 evidence_hash 发起挑战，需押 challenge_bond（由服务端中继账户垫付，dev 链联调用）。
架构：MetaMask personal_sign 仅证明 EVM 地址所有权 + 防重放 + 限流；链上 MsgChallengeAttestation 由宿主机 watcher 用链 key 签发——你的 EVM 私钥不离开 MetaMask。

MetaMask 连接

未连接

可挑战的 Attestation

发起挑战

app_id（64 hex，从列表选取或手填）

epoch

evidence_hash（64 hex；留空 = 随机演示值）

执行记录（最近 50 条）

奖励（查看 / 领取）

链上没有「按笔领取」：UGE 为 epoch 提交 attestation，挑战窗口过后由 permissionless 的 MsgFinalizeAttestation 一次性结算，奖励由链自动从奖励池转入 app owner。这里的「领取」= 对挑战窗已过、尚未终局的 attestation 触发这笔结算交易（服务端中继代发，gas 由中继账户垫付）。
架构：MetaMask personal_sign 仅证明 EVM 地址所有权 + 防重放 + 限流；链上交易由宿主机 watcher 用链 key 签发——你的 EVM 私钥不离开 MetaMask。

MetaMask 连接

未连接

查看奖励

可领取（挑战窗已过、未终局）

查看奖励后自动刷新。

领取记录（最近 50 条）

申报 Attestation（MetaMask 签名 → 服务端中继上链）

申报 = 把一段时间窗口内的订单证据打包成 attestation 承诺提交上链：三个 sha-256 哈希（attestation_hash / evidence_root / result_commitment）+ 该 epoch 的 reward_requested（auptick 整数）。挑战窗口（默认 500 块）过后即可在「奖励」tab 触发结算发放。
链上约束：发送者必须是应用注册的 attestation_submitter——此处由宿主机链 key（mykey）代签，(app_id, epoch) 键唯一、重复提交会被链拒绝。
架构：MetaMask personal_sign 仅证明 EVM 地址所有权 + 防重放 + 限流；链上 MsgSubmitAttestation 由宿主机 watcher 签发——你的 EVM 私钥不离开 MetaMask。

MetaMask 连接

未连接

提交申报

app_id（64 hex；留空 = 顶部已连接的 app_id）

epoch（须已有预算且开放）

reward_requested（auptick 整数；默认 10 uptick = 10000000000000000000；1 uptick = 1e18 auptick；受 epoch 预算约束）

attestation_hash（64 hex；填好 app_id + epoch 后自动派生，可手改）

evidence_root（64 hex；自动派生，可手改）

result_commitment（64 hex；自动派生，可手改）

申报记录（最近 50 条）

数据契约速查

QBT 字段约束

字段	约束
app_id	32 字节小写 hex（64 字符）
tier	枚举 A/B/C（emitter uint8：A=0 B=1 C=2）
action_type	PAID_ORDER=0 · QUALIFIED_ACTIVATION=1 · QUALIFIED_RETENTION=2 · VERIFIED_SERVICE=3；须在应用 profile 白名单内
underlying_action_id	1-128 UTF-8 字节；同族 QBT 的分组键
gross / refund	十进制整数字符串 ^0$\|^[1-9][0-9]*$（最小单位），refund ≤ gross
proof_hash	32 字节 hex；建议 SHA-256(规范化订单证据 JSON)

family_id 计算

family_id = SHA-256( "UGE-QBT-FAMILY-V1" || 0x00 || app_id(32 原始字节) || underlying_action_id(UTF-8) )

Family 结算语义

状态	含义
ACCEPTED_PRIMARY	族内首笔，qnr += net
DEDUPLICATED_FAMILY	同族同参重放，0 计入
CONFLICTED_FAMILY / REJECTED_FAMILY_CONFLICT	同族参数冲突，整族回退（qnr -= 族 net）
REJECTED_DUPLICATE_SOURCE	source_ref 重复（链上路径 = evm:{chain}:{tx}:{log}，天然唯一）

Webhook 事件

事件	触发	载荷
webhook.test	配置 webhook 后立即	configured_at
qbt.processed	QBT 结算（链 sync 或直传）	status / family_id / qnr / ail（+ chain_id / block_height）
pav.created	PAV 构建成功	epoch / pav_id / integrity / verification_valid

链上调用

QBTEmitter @ 0x472D4Ac31581AA8349ca8E2c1f42C87Daee5b09F（uptick_7777-1 · EVM 7777 · registry uptick-dev-7777-emitter-0.1.0）
reportQBT(bytes32 appId, uint8 tier, uint8 actionType, address subject,
          string underlyingActionId, string denom, uint256 gross, uint256 refund, bytes32 proofHash)
防重：qbtId = keccak256(chainid, emitter, reporter, familyId, proofHash) → 重复 revert "duplicate QBT"

完整规格见 docs/DEVELOPER-CONSOLE-DATA-SPEC-0.1.md；接入步骤见《UGE接入开发文档》。