seeker-genesis-token

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Seeker Genesis Token verification

Seeker Genesis Token验证

The Seeker Genesis Token (SGT) is a Token-2022 NFT minted once per Seeker device. Holding one is evidence of owning a Seeker, which makes it useful for gating rewards and for one-claim-per-device logic.

Verification has two halves, and both are required:

Prove the user controls the wallet — Sign-in-with-Solana (SIWS)
Prove that wallet holds an SGT — inspect the wallet's Token-2022 mints

Doing only the second means anyone can submit a real Seeker owner's public address and pass. Doing only the first proves wallet control but says nothing about a device.

Seeker Genesis Token（SGT）是一种Token-2022标准的NFT，每个Seeker设备仅铸造一次。持有SGT即可证明用户拥有Seeker设备，因此可用于限制奖励发放、实现“每设备仅可申领一次”的逻辑。

验证流程分为两部分，两者缺一不可：

证明用户控制钱包 —— Sign-in-with-Solana（SIWS）
证明该钱包持有SGT —— 检查钱包中的Token-2022铸币记录

仅完成第二步意味着任何人都可以提交真实Seeker所有者的公钥地址通过验证；仅完成第一步只能证明用户控制钱包，但无法证明其拥有设备。

This must run on a server

必须在服务器端运行此流程

Never decide entitlement client-side. A client can be patched, so a client-side

hasSGT

boolean is worth nothing. The client's job is to collect a signature; the server verifies it and owns the result.

Requirements:

A backend you control that can make Solana mainnet RPC calls
Storage for nonces and claim records
An RPC endpoint. A paid provider helps, since the check may enumerate many token accounts — keep that key server-side only, never in an
```
EXPO_PUBLIC_*
```
variable

绝不要在客户端判断用户是否有权限。客户端代码可被篡改，因此客户端的

hasSGT

布尔值毫无意义。客户端的职责是收集签名，而服务器负责验证签名并决定最终结果。

需求：

由你掌控的后端服务，能够调用Solana主网RPC接口
用于存储随机数（nonce）和申领记录的存储服务
一个RPC端点。建议使用付费服务商，因为检查过程可能需要遍历多个代币账户——请务必将RPC密钥仅保存在服务器端，绝不要存入
```
EXPO_PUBLIC_*
```
变量中

Prerequisites

前置条件

A working wallet connection. If the app has none, use the

solana-mobile-wallet

skill first; this skill assumes

useMobileWallet()

is available.

Testing needs a physical Seeker device — an emulator cannot hold an SGT. Plan for a code path you can exercise without one, such as a server-side allowlist in development.

已实现有效的钱包连接。如果应用尚未集成钱包，请先使用

solana-mobile-wallet

技能；本技能假设

useMobileWallet()

已可用。

测试需要真实的Seeker设备——模拟器无法持有SGT。请规划一条无需Seeker设备即可测试的代码路径，例如开发环境中的服务器端白名单。

Step 1: issue a nonce from the server

步骤1：从服务器获取随机数（nonce）

The nonce must be server-generated, single-use, and short-lived. A client-generated or reusable nonce makes the signature replayable, which defeats the exercise.

// POST /api/siws/nonce
const nonce = crypto.randomBytes(16).toString('hex')
await store.put(nonce, { issuedAt: Date.now(), used: false }, { ttlSeconds: 300 })
return { nonce }

随机数必须由服务器生成、单次使用且有效期短。如果由客户端生成或可重复使用，签名将可被重放，导致验证流程失效。

// POST /api/siws/nonce
const nonce = crypto.randomBytes(16).toString('hex')
await store.put(nonce, { issuedAt: Date.now(), used: false }, { ttlSeconds: 300 })
return { nonce }

Step 2: sign in on the client

步骤2：在客户端完成登录签名

signIn

from the wallet hook authorizes and proves ownership in a single prompt:

import { useMobileWallet } from '@wallet-ui/react-native-kit'

const { signIn } = useMobileWallet()

const output = await signIn({
  address: account.address.toString(),
  chainId: 'solana:mainnet',
  domain: 'yourdapp.com',
  issuedAt: new Date().toISOString(),
  nonce, // from step 1
  statement: 'Sign in to verify Seeker ownership',
  uri: 'https://yourdapp.com',
  version: '1',
})

chainId

is pinned to

solana:mainnet

deliberately rather than taken from the hook's

chain

: SGTs exist only on mainnet, so a signature scoped to devnet proves nothing about a device.

This is the fully-specified payload, not the short

signIn

form —

nonce

domain

, and

version

are what make the signature non-replayable and bind it to your app. The

solana-mobile-wallet

skill covers both forms and when each is appropriate.

Post

output

to the server.

钱包钩子中的

signIn

方法可通过一次授权操作证明用户所有权：

import { useMobileWallet } from '@wallet-ui/react-native-kit'

const { signIn } = useMobileWallet()

const output = await signIn({
  address: account.address.toString(),
  chainId: 'solana:mainnet',
  domain: 'yourdapp.com',
  issuedAt: new Date().toISOString(),
  nonce, // 来自步骤1
  statement: 'Sign in to verify Seeker ownership',
  uri: 'https://yourdapp.com',
  version: '1',
})

chainId

被固定为

solana:mainnet

，而非取自钩子中的

chain

值：因为SGT仅存在于主网，所以针对devnet的签名无法证明用户拥有设备。

这是完整的参数 payload，而非简化版的

signIn

调用——

nonce

、

domain

和

version

是确保签名不可重放并与你的应用绑定的关键。

solana-mobile-wallet

技能涵盖了两种调用形式及其适用场景。

将

output

提交至服务器。

Step 3: verify the signature on the server

步骤3：在服务器端验证签名

bash

npm install @solana/wallet-standard-util

import { verifySignIn } from '@solana/wallet-standard-util'

function verifySiws(payload, result) {
  return verifySignIn(payload, {
    account: { ...result.account, publicKey: new Uint8Array(result.account.publicKey) },
    signature: new Uint8Array(result.signature),
    signedMessage: new Uint8Array(result.signedMessage),
  })
}

bash

npm install @solana/wallet-standard-util

import { verifySignIn } from '@solana/wallet-standard-util'

function verifySiws(payload, result) {
  return verifySignIn(payload, {
    account: { ...result.account, publicKey: new Uint8Array(result.account.publicKey) },
    signature: new Uint8Array(result.signature),
    signedMessage: new Uint8Array(result.signedMessage),
  })
}

Step 4: check the wallet for an SGT

步骤4：检查钱包是否持有SGT

See references/sgt-verification.md for the full implementation. It confirms three properties of a Token-2022 mint — mint authority, metadata pointer, and token group membership — and all three must match.

完整实现请参考references/sgt-verification.md。该文档会验证Token-2022铸币的三个属性——铸币权限、元数据指针和代币组归属，且三个属性必须全部匹配。

Step 5: combine the checks correctly

步骤5：正确组合各项检查

This is where the subtle bug lives. The address whose SGT you check must be the address that signed, read out of the verified payload — not an address the client sent alongside it:

async function verifySeekerUser({ payload, result }) {
  // 1. The nonce must be one we issued, unused, and unexpired.
  const record = await store.get(payload.nonce)
  if (!record || record.used) throw new Error('Invalid or reused nonce.')
  await store.markUsed(payload.nonce)

  // 2. The signature must be valid for that payload.
  if (!verifySiws(payload, result)) throw new Error('Invalid signature.')

  // 3. The domain must be ours, or a signature farmed by another site would pass.
  if (payload.domain !== 'yourdapp.com') throw new Error('Wrong domain.')

  // 4. Check the SGT against the *signed* address only.
  const { hasSGT, mintAddress } = await checkWalletForSGT(payload.address)

  return { address: payload.address, hasSGT, mintAddress }
}

Taking the address from anywhere other than the verified payload lets a caller submit a real Seeker owner's address with their own signature and be granted access.

这是容易出现隐性bug的环节。你要检查SGT的地址必须是签名对应的地址，即从已验证的payload中读取，而非客户端附带发送的其他地址：

async function verifySeekerUser({ payload, result }) {
  // 1. 随机数必须是我们发放的、未使用且未过期的。
  const record = await store.get(payload.nonce)
  if (!record || record.used) throw new Error('Invalid or reused nonce.')
  await store.markUsed(payload.nonce)

  // 2. 签名必须对应该payload。
  if (!verifySiws(payload, result)) throw new Error('Invalid signature.')

  // 3. 域名必须是我们的，否则其他网站获取的签名也会通过验证。
  if (payload.domain !== 'yourdapp.com') throw new Error('Wrong domain.')

  // 4. 仅针对签名对应的地址检查SGT。
  const { hasSGT, mintAddress } = await checkWalletForSGT(payload.address)

  return { address: payload.address, hasSGT, mintAddress }
}

如果从已验证payload以外的地方获取地址，攻击者可以提交真实Seeker所有者的地址并附上自己的签名，从而获取权限。

Anti-Sybil: one claim per device

反女巫攻击：每设备仅可申领一次

An SGT is per-device, so the mint address is the device identity. Store that, not the wallet address — a wallet can hold a different SGT later, and a device's SGT can move between wallets.

const { hasSGT, mintAddress } = await verifySeekerUser({ payload, result })
if (!hasSGT) throw new Error('No Seeker Genesis Token found.')

if (await claims.exists(mintAddress)) throw new Error('This device has already claimed.')
await claims.insert({ claimedAt: new Date(), mintAddress })

Have

checkWalletForSGT

return the mint address rather than a bare boolean — see the end of the reference file.

SGT是与设备绑定的，因此**铸币地址（mint address）**即为设备标识。请存储铸币地址而非钱包地址——一个钱包后续可能持有其他SGT，而设备的SGT也可能在不同钱包间转移。

const { hasSGT, mintAddress } = await verifySeekerUser({ payload, result })
if (!hasSGT) throw new Error('No Seeker Genesis Token found.')

if (await claims.exists(mintAddress)) throw new Error('This device has already claimed.')
await claims.insert({ claimedAt: new Date(), mintAddress })

请让

checkWalletForSGT

返回铸币地址而非单纯的布尔值——详见参考文档末尾。

Reference material

参考资料

references/sgt-verification.md — full verification implementation, SGT constants, standard-RPC and Helius variants

references/sgt-verification.md —— 完整验证实现、SGT常量、标准RPC和Helius变体

Related skills

链接

Detecting Seeker users: https://docs.solanamobile.com/react-native/detecting-seeker-users
Sign-in-with-Solana spec: https://github.com/phantom/sign-in-with-solana

检测Seeker用户：https://docs.solanamobile.com/react-native/detecting-seeker-users
Sign-in-with-Solana规范：https://github.com/phantom/sign-in-with-solana