# spendable-credit

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

# Spendable Credit

Instruction text for agents that use the Spendable Credit skill, loaded by `bb dev skills spendable-credit` 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 spendable-credit skill and build me one: immutable whole service credits: purchase fixed or scaled packs, then consume on chain for a provider-issued request. Nontransferable; requires provider receipt verification. 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 spendable-credit` prints the same instructions.

## Summary

Required standards: ["Spendable Credit"]

- Build with build_standard type spendable-credit or bb build spendable-credit.
- Provider, serviceId, payment asset, expiry and approvals are immutable.
- Purchase options are fixed or scaled whole packs, with optional per-purchase maximum; omitted maximum uses safe uint64 limits.
- Only the holder may consume whole credits. No peer transfer, wrapper, merchant debit or automatic refund.
- Service requires confirmed receipt verification and durable authenticated request deduplication, never a sign-in balance.

## Executable contract

Resolve missing clarifications before building. Postconditions describe the chosen parameters. Reference example postconditions apply only to the example input; they are not defaults for a new request. Unsupported behavior must remain explicit. Golden evaluations are experimental diagnostic evidence, not a source of truth; listing a scenario ID does not prove this artifact was executed or verified.

```json
{
  "version": 1,
  "prerequisites": [
    "Confirm signer and network before handoff.",
    "Record exact user requirements separately from external metadata."
  ],
  "postconditions": [
    "Generated artifact matches the confirmed input parameters and explicit user intent.",
    "Structural checks and lifecycle evidence remain separately scoped; unsigned output is not deployed."
  ],
  "examplePostconditions": [
    "Prepare a new collection",
    "Disallow forceful post-mint transfers",
    "Only purchase and consumption paths",
    "Payment goes to the service provider",
    "Ten credits per pack",
    "At most three packs per purchase",
    "Only holder-initiated consumption",
    "Consumption sends credits to burn address",
    "Purchase expiry is inclusive",
    "Consumption shares expiry",
    "Purchase and consumption terms cannot be changed"
  ],
  "clarifications": [
    "Confirm recipient, asset identity and intended manager powers."
  ],
  "unsupported": [
    "Unsigned builder proposal only; signer and manager must be bound before deployment.",
    "Artifact constraints only. No chain execution, wallet signing, live balance checks or external service verification.",
    "Recipient payment excludes protocol fees and transaction gas."
  ],
  "goldenScenarioIds": [
    "spendable-service-credits"
  ],
  "example": {
    "tool": "build_spendable_credit",
    "input": {
      "uri": "ipfs://METADATA_COLLECTION",
      "paymentDenom": "BADGE",
      "provider": "bb1xvenxvenxvenxvenxvenxvenxvenxvenlrd2nm",
      "serviceId": "image-generation",
      "purchaseOptions": [
        {
          "pricePerPack": "1000000",
          "creditsPerPack": "10",
          "purchaseType": "scaled",
          "maxPacks": "3"
        }
      ],
      "expiresAt": "1896048000000"
    }
  }
}
```

## Instructions

## Spendable Credit Configuration

Use the dedicated builder; do not retrofit consumption into Credit Token collections.
Set provider (valid bb1 address), serviceId, paymentDenom and metadata. Supply purchaseOptions with pricePerPack (payment base units), creditsPerPack (whole credits), purchaseType (fixed or scaled), and optional maxPacks. Legacy top-level pricePerPack and creditsPerPack represent one unlimited scaled option; do not combine both forms. Optional expiresAt is inclusive Unix milliseconds and limits purchase and consumption.

The profile freezes approvals, uses only token 1 and permanent ownership times, prevents peer transfers and wrappers, and permits only paid mint plus holder-authorized burn. Do not add custom approvals or permission overrides: strict inspection must reject them.

Read terms with bb spendable-credits show. Quote with bb spendable-credits quote COLLECTION --units PACKS, and purchase with bb spendable-credits purchase COLLECTION --creator WALLET --units PACKS. Multiple options require --approval-id. Packs must be whole; do not round user payments or fractional service units. Per-purchase caps do not limit lifetime purchases.

Consume with bb spendable-credits consume COLLECTION --creator WALLET --units CREDITS --request-id REQUEST. First obtain an authenticated provider-issued request. The provider must fetch a successful confirmed native execution, verify holder, collection, provider, service, exact units and request ID, and atomically deduplicate request and receipt. EVM receipt status alone is insufficient; verified native tokenization execution is required. Never put private request credentials in transaction memos or public URLs.

After ambiguous submission, reconcile the same transaction rather than burn again. A burn does not atomically deliver an external service: providers need idempotent fulfillment, durable retries and a disclosed failure policy. Expired credits cannot be spent, but prior confirmed receipts remain claimable. There is no standing debit consent to revoke.

See docs/spendable-credits.md and examples/spendable-credit-provider for the authenticated durable integration. The increment-only Credit Token standard remains available when the provider tracks usage separately.