# quest

<!-- generated by site/scripts/gen-skills.ts; do not hand-edit -->

# Quest

Instruction text for agents that use the Quest skill, loaded by `bb dev skills quest` and the MCP `get_skill_instructions` tool.

## Try it

Paste this into Claude Code, Codex, or Cursor with the BitBadges MCP server wired. The agent loads the skill, builds, verifies, and hands back a link to review and sign.

```text
Load the quest skill and build me one: quest/reward collection: users complete criteria and claim a badge + coin payout. Use the session tools, run validate, review, and simulate in parallel, fix anything critical, then call get_review_url and give me the link.
```

From a shell, `bb dev skills quest` prints the same instructions.

## Summary

Required standards: ["Quests"]

- Single token only: validTokenIds = [{start: "1", end: "1"}]
- Quest approval must be properly gated, typically via an off-chain claim (merkle challenge with claimConfig), but can also use on-chain criteria (mustOwnTokens, dynamicStoreChallenges, evmQueryChallenges, votingChallenges)
- Coin transfers with overrideFromWithApproverAddress: true + overrideToWithInitiator: true
- predeterminedBalances: amount 1, no increments, no recurring, no duration
- Escrow funded upfront via set_mint_escrow_coins (rewardAmount * maxClaims)
- invariants.noCustomOwnershipTimes: true
- Permissions: use "locked-approvals" preset (recommended)
- Default balances: empty balances, all auto-approve flags true

## Instructions

## Quest Configuration

### Mental Model

A quest collection rewards users for completing criteria. Users receive a quest badge (token 1) + coin payout.

The quest approval must be properly gated so that only eligible users can claim. Gating options:
- **Off-chain claim (most common)**: A merkle challenge with claimConfig containing plugins (password, codes, whitelist, etc.). The claim is verified off-chain by BitBadges, and a merkle proof is issued for on-chain redemption.
- **On-chain criteria**: mustOwnTokens (require holding specific tokens/badges), dynamicStoreChallenges, evmQueryChallenges, votingChallenges, these are checked directly on-chain during the transfer.
- **Both**: Combine off-chain claims with on-chain criteria for layered verification.

Choose the gating approach based on the user's request. If they mention passwords, codes, or whitelists, use an off-chain claim. If they mention token ownership or on-chain conditions, use the corresponding on-chain criteria.

### Build Steps (call all in parallel in one round)

1. `set_standards` → `["Quests"]`
2. `set_valid_token_ids` → `[{ "start": "1", "end": "1" }]`
3. `set_invariants` → `{ "noCustomOwnershipTimes": true }`
4. `set_permissions` → `{ "preset": "locked-approvals" }`
5. `set_default_balances` → empty balances, all auto-approve true
6. `set_collection_metadata` / `set_token_metadata`: descriptive content
7. `add_approval`: the quest approval (see exact structure below)
8. **`set_mint_escrow_coins`**: required for coin rewards. Amount = rewardPerClaim × maxClaims.

### Quest Approval (add_approval)

Use approvalId `"quest-approval"`. The exact approvalCriteria structure:

```json
{
  "approvalId": "quest-approval",
  "fromListId": "Mint",
  "toListId": "All",
  "initiatedByListId": "All",
  "tokenIds": [{"start":"1","end":"1"}],
  "approvalCriteria": {
    "overridesFromOutgoingApprovals": true,
    "maxNumTransfers": {
      "overallMaxNumTransfers": "<maxClaims>"
    },
    "predeterminedBalances": {
      "manualBalances": [],
      "incrementedBalances": {
        "startBalances": [{ "amount": "1", "tokenIds": [{"start":"1","end":"1"}], "ownershipTimes": [{"start":"1","end":"18446744073709551615"}] }],
        "incrementTokenIdsBy": "0",
        "incrementOwnershipTimesBy": "0",
        "durationFromTimestamp": "0",
        "allowOverrideTimestamp": false,
        "recurringOwnershipTimes": { "startTime": "0", "intervalLength": "0", "chargePeriodLength": "0" }
      },
      "orderCalculationMethod": {
        "useOverallNumTransfers": true,
        "usePerToAddressNumTransfers": false,
        "usePerFromAddressNumTransfers": false,
        "usePerInitiatedByAddressNumTransfers": false,
        "useMerkleChallengeLeafIndex": false,
        "challengeTrackerId": ""
      }
    },
    "coinTransfers": [{
      "to": "",
      "overrideFromWithApproverAddress": true,
      "overrideToWithInitiator": true,
      "coins": [{ "amount": "<rewardAmount>", "denom": "<rewardDenom>" }]
    }]
  }
}
```

**Gating**: add one OR more of these to approvalCriteria based on the user's request:
- **Off-chain claim**: `"merkleChallenges": [{ "root": "", "expectedProofLength": "0", "maxUsesPerLeaf": "1", "uri": "", "customData": "", "useCreatorAddressAsLeaf": false, "claimConfig": { "approach": "in-site", "label": "...", "plugins": [...] } }]`
- **Token ownership**: `"mustOwnTokens": [{ "collectionId": "...", "amountRange": {"start":"1","end":"18446744073709551615"}, ... }]`. Use collectionId "0" to self-reference this collection (e.g., require holding token 1 from this quest collection itself).
- **Dynamic store**: `"dynamicStoreChallenges": [...]`
- **EVM query**: `"evmQueryChallenges": [...]`

Off-chain claims are the most common for quests (passwords, codes, whitelists). On-chain criteria can be combined with or used instead of claims.

### Escrow Funding (required)

Call `set_mint_escrow_coins` in the same round as the other tools. Example for 10 ATOM reward × 50 claims:
```ts
set_mint_escrow_coins({ coins: [{ denom: "ibc/A4DB...", amount: "500000000" }] })
```
Without this, the escrow has no funds and claims will fail.

### Common Mistakes

- Don't add extra fields to coinTransfers, the only fields are: to, overrideFromWithApproverAddress, overrideToWithInitiator, coins. No startTime, no other fields.
- Don't omit `manualBalances: []` in predeterminedBalances, SDK crashes without it
- Don't omit fields in orderCalculationMethod, include all boolean fields
- Don't forget `set_mint_escrow_coins`: without it, the escrow is empty and rewards can't be paid
- Don't set maxUsesPerLeaf to anything other than "1", each user claims once
- Don't set allowOverrideTimestamp: true, quests require false
- Don't set useCreatorAddressAsLeaf: true, quests require false