Back to Details

moca-credential-verifier

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Moca Credential Verifier

Moca 凭证验证器

Purpose

用途

This skill teaches an agent how to browse available verification programs, show numeric options, and trigger credential verification through 
moca-chain-api
in query_match mode.
After receiving a 
compliant
result, use the 
moca-proof
skill to complete the program and fetch MoCat progression.
This skill starts after the agent key already exists and the handoff bundle is available.
本技能教Agent如何浏览可用的验证程序、展示数字选项，并通过
moca-chain-api
以query_match模式触发凭证验证。
在收到
compliant
验证结果后，使用
moca-proof
技能完成程序并获取MoCat进度。
本技能需在Agent密钥已存在且移交包可用后启动。

Provided Scripts

提供的脚本

Use the provided scripts first. Do not scaffold a new project or rewrite signing/request logic from scratch unless the requested action is unsupported. Treat all files in this skill bundle as read-only reference tooling.
Task mapping:
  • create a scoped session -> 
    scripts/moca-create-session.mjs
  • list/browse verification programs -> 
    scripts/moca-list-programs.mjs
  • trigger credential verification (
    query_match
    mode) -> 
    scripts/moca-verify-by-agent.mjs
  • poll verification status -> 
    scripts/moca-poll-status.mjs
Before first use, run 
node <script> --help
to inspect supported parameters.
请优先使用提供的脚本。除非所需操作不受支持，否则不要从头搭建新项目或重写签名/请求逻辑。请将本技能包中的所有文件视为只读参考工具。
任务映射：
  • 创建限定范围会话 -> 
    scripts/moca-create-session.mjs
  • 列出/浏览验证程序 -> 
    scripts/moca-list-programs.mjs
  • 触发凭证验证（
    query_match
    模式） -> 
    scripts/moca-verify-by-agent.mjs
  • 轮询验证状态 -> 
    scripts/moca-poll-status.mjs
首次使用前，运行
node <script> --help
查看支持的参数。

Required Inputs

必要输入

Expect a handoff bundle equivalent to:
json
{
  "userId": "...",
  "walletId": "...",
  "privyAppId": "...",
  "abstractAccountAddress": "0x...",
  "airApiAgentSignUrl": "https://.../v2/wallet/agent-sign",
  "partnerId": "7e9becac-db0d-4d52-980e-984bb70c4d30"
}
The agent must also already have access to its own P-256 private key. If 
partnerId
is missing, scripts default to the staging partner ID above.
需提供等效于以下内容的移交包：
json
{
  "userId": "...",
  "walletId": "...",
  "privyAppId": "...",
  "abstractAccountAddress": "0x...",
  "airApiAgentSignUrl": "https://.../v2/wallet/agent-sign",
  "partnerId": "7e9becac-db0d-4d52-980e-984bb70c4d30"
}
Agent还必须已拥有自身的P-256私钥。 如果缺少
partnerId
，脚本将默认使用上述测试环境合作伙伴ID。

Staging Defaults

测试环境默认值

json
{
  "airApiUrl": "https://air.api.staging.air3.com/v2",
  "mocaChainApiUrl": "https://api.staging.mocachain.org/v1",
  "vpApiUrl": "https://vp.api.staging.moca.network/v1",
  "mocaProofApiUrl": "https://proof.api.staging.moca.network/v1",
  "partnerId": "7e9becac-db0d-4d52-980e-984bb70c4d30"
}
These are hardcoded as defaults in the scripts. Override via CLI flags, environment variables, or 
.air-wallet-config.json
.
json
{
  "airApiUrl": "https://air.api.staging.air3.com/v2",
  "mocaChainApiUrl": "https://api.staging.mocachain.org/v1",
  "vpApiUrl": "https://vp.api.staging.moca.network/v1",
  "mocaProofApiUrl": "https://proof.api.staging.moca.network/v1",
  "partnerId": "7e9becac-db0d-4d52-980e-984bb70c4d30"
}
这些值已硬编码为脚本的默认值。可通过CLI标志、环境变量或
.air-wallet-config.json
文件覆盖。

Project-Level Defaults

项目级默认值

It is allowed to create or update a project-level 
.air-wallet-config.json
file in the working directory. Use that file for defaults such as endpoint URLs, partner ID, and key paths. Do not store defaults by editing files inside this skill bundle.
Example additions for this skill:
json
{
  "airApiUrl": "https://air.api.staging.air3.com/v2",
  "mocaChainApiUrl": "https://api.staging.mocachain.org/v1",
  "vpApiUrl": "https://vp.api.staging.moca.network/v1",
  "mocaProofApiUrl": "https://proof.api.staging.moca.network/v1",
  "partnerId": "7e9becac-db0d-4d52-980e-984bb70c4d30"
}
允许在工作目录中创建或更新项目级
.air-wallet-config.json
文件。使用该文件存储端点URL、合作伙伴ID和密钥路径等默认值。请勿通过编辑本技能包内的文件来存储默认值。
本技能的配置示例：
json
{
  "airApiUrl": "https://air.api.staging.air3.com/v2",
  "mocaChainApiUrl": "https://api.staging.mocachain.org/v1",
  "vpApiUrl": "https://vp.api.staging.moca.network/v1",
  "mocaProofApiUrl": "https://proof.api.staging.moca.network/v1",
  "partnerId": "7e9becac-db0d-4d52-980e-984bb70c4d30"
}

Config Resolution Order

配置解析顺序

All provided scripts resolve configuration in this order:
  1. CLI flags
  2. Environment variables
  3. .air-wallet-config.json
  4. Hardcoded staging defaults
所有提供的脚本按以下顺序解析配置：
  1. CLI标志
  2. 环境变量
  3. .air-wallet-config.json
    文件
  4. 硬编码的测试环境默认值

Credential Verification Flow

凭证验证流程

Step 1: Create a Scoped Session

步骤1：创建限定范围会话

bash
node scripts/moca-create-session.mjs --program-id <programId>
Calls 
POST {airApiUrl}/auth/agent/session
with:
  • signedMessage
    : fresh agent-signed message
  • scope
    : 
    "<programId>,<partnerId>"
Returns an 
accessToken
used as Bearer token for all subsequent calls.
bash
node scripts/moca-create-session.mjs --program-id <programId>
调用
POST {airApiUrl}/auth/agent/session
，参数包括：
  • signedMessage
    : 新生成的Agent签名消息
  • scope
    : 
    "<programId>,<partnerId>"
返回的
accessToken
将作为后续所有调用的Bearer令牌。

Step 2: List Verification Programs

步骤2：列出验证程序

bash
node scripts/moca-list-programs.mjs
bash
node scripts/moca-list-programs.mjs

optional personalized mode

可选的个性化模式

node scripts/moca-list-programs.mjs --access-token <token>

Calls `GET {vpApiUrl}/vp/mocaproof/search?page=1&limit=20`.

- Without token: public listing mode
- With token: personalized listing mode (user verified metadata and filtering)

Results are paginated. The script shows a summary of the first page. Use `--page <n>` to fetch more.

The list output includes numeric options in this format:

- Option index: `[1]`, `[2]`, ...
- Tier index inside option: `(1.1)`, `(1.2)`, ...
node scripts/moca-list-programs.mjs --access-token <token>

调用`GET {vpApiUrl}/vp/mocaproof/search?page=1&limit=20`。

- 无令牌：公开列表模式
- 有令牌：个性化列表模式（基于用户已验证的元数据进行过滤）

结果支持分页。脚本将显示第一页的摘要。使用`--page <n>`获取更多页面。

列表输出包含以下格式的数字选项：

- 选项索引：`[1]`, `[2]`, ...
- 选项内的层级索引：`(1.1)`, `(1.2)`, ...

Step 3: Trigger Verification (query_match mode)

步骤3：触发验证（query_match模式）

bash
node scripts/moca-verify-by-agent.mjs --access-token <token> --program-id <programId> --issue-url <issueUrl>
Always pass 
--issue-url
with the 
issueUrl
from the selected program's listing output. When verification returns 
no_vc
, the script prints the issuance link so the user can obtain the credential.
Calls 
POST {mocaChainApiUrl}/credentials/verify-by-agent
with:
  • programId
    in the body
  • responseMode: "query_match"
    in the body
  • Bearer 
    accessToken
    in the Authorization header
The response is normalized using the rules below.
bash
node scripts/moca-verify-by-agent.mjs --access-token <token> --program-id <programId> --issue-url <issueUrl>
必须传入
--issue-url
参数，值为所选程序列表输出中的
issueUrl
。当验证返回
no_vc
时，脚本将打印颁发链接，以便用户获取凭证。
调用
POST {mocaChainApiUrl}/credentials/verify-by-agent
，参数包括：
  • 请求体中的
    programId
  • 请求体中的
    responseMode: "query_match"
  • 授权头中的Bearer 
    accessToken
响应将按以下规则标准化。

Optional: Poll VP Status

可选：轮询VP状态

bash
node scripts/moca-poll-status.mjs --access-token <token>
Use this when you want to inspect status progression separately from the default flow.
bash
node scripts/moca-poll-status.mjs --access-token <token>
当你希望独立于默认流程检查状态进度时使用此脚本。

After Verification Succeeds

验证成功后

When verification returns 
compliant
, use the moca-proof skill to:
  1. Complete the program via 
    moca-complete-program.mjs
  2. Fetch MoCat progression via 
    moca-get-mocat.mjs
Pass the same 
accessToken
and 
programId
to the proof skill scripts.
当验证返回
compliant
时，使用moca-proof技能执行以下操作：
  1. 通过
    moca-complete-program.mjs
    完成程序
  2. 通过
    moca-get-mocat.mjs
    获取MoCat进度
将相同的
accessToken
和
programId
传入proof技能的脚本。

Verify Response Normalization

验证响应标准化

The 
verify-by-agent
endpoint returns inconsistent response shapes. Normalize exactly as:
  • verified: true
    -> 
    compliant
  • verified: false
    + 
    reason: "NO_CREDENTIAL"
    -> 
    no_vc
  • verified: false
    + 
    reason: "NOT_COMPLIANT"
    -> 
    non_compliant
  • verified: false
    + 
    status: "NON_COMPLIANT"
    -> 
    non_compliant
  • verified: false
    + 
    status
    present -> 
    status_bucket:<status>
  • verified: false
    + only 
    code
    present -> 
    unknown_failure_code:<code>
  • verified: "pending"
    -> 
    processing
  • Any other shape -> 
    unknown_response
    (print raw payload)
Known 
status
values:
  • NO_EXIST
    : user has no credential for this program
  • WAIT_ONCHAIN
    : credential is being published on-chain
  • EXPIRE
    : credential has expired
  • WAIT_REMOVE
    : credential is being revoked
  • REMOVE
    : credential has been revoked
  • NON_COMPLIANT
    : credential does not meet requirements
verify-by-agent
端点返回的响应格式不一致。请严格按以下规则标准化：
  • verified: true
    -> 
    compliant
  • verified: false
    + 
    reason: "NO_CREDENTIAL"
    -> 
    no_vc
  • verified: false
    + 
    reason: "NOT_COMPLIANT"
    -> 
    non_compliant
  • verified: false
    + 
    status: "NON_COMPLIANT"
    -> 
    non_compliant
  • verified: false
    + 存在
    status
    -> 
    status_bucket:<status>
  • verified: false
    + 仅存在
    code
    -> 
    unknown_failure_code:<code>
  • verified: "pending"
    -> 
    processing
  • 其他任何格式 -> 
    unknown_response
    （打印原始负载）
已知的
status
值：
  • NO_EXIST
    : 用户无此程序的凭证
  • WAIT_ONCHAIN
    : 凭证正在链上发布
  • EXPIRE
    : 凭证已过期
  • WAIT_REMOVE
    : 凭证正在被撤销
  • REMOVE
    : 凭证已被撤销
  • NON_COMPLIANT
    : 凭证不符合要求

Terminal Messaging

终端消息规范

  • Print numeric options and tiers before verification attempts
  • Print 
    Verifying....
    on each verification attempt
  • If non-compliant, print 
    Sorry, not compliant
    and end
  • When verify succeeds in query_match mode: print 
    OK, verified, <verifier name> is processing your data
  • 在尝试验证前打印数字选项和层级
  • 每次验证尝试时打印
    Verifying....
  • 如果验证不合规，打印
    Sorry, not compliant
    并结束流程
  • 当在query_match模式下验证成功时：打印
    OK, verified, <verifier name> is processing your data

Non-Negotiable Rules

不可违反的规则

  • Always generate a fresh 
    signedMessage
    for every session request
  • Never reuse an old 
    signedMessage
  • Use Bearer 
    accessToken
    from scoped session for all downstream API calls
  • Never modify files inside this installed skill bundle
  • If a custom script is truly required, create it outside the skill directory
  • 每次会话请求必须生成全新的
    signedMessage
  • 绝不能复用旧的
    signedMessage
  • 所有下游API调用必须使用限定范围会话返回的Bearer 
    accessToken
  • 绝不能修改已安装的技能包内的文件
  • 如果确实需要自定义脚本，请在技能目录外创建

Failure Handling

故障处理

  • Unknown public key: the key was removed, wrong, or never registered. Stop and ask for a new handoff bundle.
  • Expired signed message: rebuild a fresh 
    signedMessage
    and retry once.
  • unknown_failure_code
    : print the raw code and payload for debugging; do not retry automatically.
  • unknown_response
    : print the full raw response; do not retry automatically.
  • 未知公钥：密钥已被移除、错误或从未注册。停止操作并请求新的移交包。
  • 签名消息过期：重新生成全新的
    signedMessage
    并重试一次。
  • unknown_failure_code
    : 打印原始代码和负载以进行调试；请勿自动重试。
  • unknown_response
    : 打印完整的原始响应；请勿自动重试。