# Bounties and crowdfunding

`Bounty` and `Crowdfund` describe different funding workflows. They use escrow and approval state; they are not interchangeable with a direct [payment obligation](https://docs.bitbadges.io/standards/payments).

## Bounties

A bounty specifies an amount and denomination, a verifier, a recipient on acceptance, a submitter who receives denial/expiry refunds, and an expiration. The builder funds the collection's mint escrow through `mintEscrowCoinsToTransfer`. The recipient and submitter must differ.

```bash
bb build bounty --amount 25 --denom USDC --verifier "$VERIFIER" \
  --recipient "$RECIPIENT" --submitter "$SUBMITTER" --expiration 30d \
  --creator "$CREATOR" --uri "$METADATA_URI"
bb bounties show "$COLLECTION_ID"
bb bounties status "$COLLECTION_ID"
```

| Action | Authorization and effect |
| --- | --- |
| `bb bounties accept <collection-id> --creator <verifier>` | Builds a vote plus acceptance transfer paying the recipient |
| `bb bounties deny <collection-id> --creator <verifier>` | Builds a vote plus denial transfer refunding the submitter |
| `bb bounties claim-refund <collection-id> --creator <signer>` | Builds the post-deadline expiry transfer; payout remains fixed to the submitter |
| `bb bounties list --mine <address> --open` | Filters the indexer's pending bounties involving that address |

Track votes, execution trackers, escrow balance, and expiration separately. A verifier decision and an executed coin payout are different events. Status distinguishes accepted, denied, pending, and expired; `expireExecuted` distinguishes an available expiry path from an executed refund.

The accept, deny, and expire approvals have independent one-use trackers. Their names do not create a shared cancellation mutex. Available escrow funds constrain actual payout execution; this page does not assert that independent counters prevent every later alternative action if escrow is replenished. An acceptance window ending at timestamp `t` includes `t`; use the actual transfer-time ranges for boundary decisions.

## Existing crowdfunding composition

The builder accepts `--goal`, `--denom`, `--crowdfunder`, and `--deadline` (default 30 days), plus collection metadata. It creates contributor receipt token ID 1 and progress token ID 2. The intended flow is contribution, goal evaluation, then success withdrawal or contributor refund.

| Existing command | Intended action |
| --- | --- |
| `bb build crowdfund --help` | Discover construction options; `bb crowdfunds build` is an alias |
| `bb crowdfunds list` / `show <collection-id>` / `status <collection-id>` | Inspect goal, raised amount, deadline, and projected state |
| `bb crowdfunds contribute <collection-id> --creator <address> --amount <n>` | Builds the deposit and progress messages together |
| `bb crowdfunds withdraw <collection-id> --creator <crowdfunder>` | Builds the success withdrawal and progress burn messages |
| `bb crowdfunds refund <collection-id> --creator <address> --amount <n>` | Builds the contributor refund after the deadline when the goal is unmet |

Contribution and refund accept `--base-units` for an explicit integer amount interpretation. Use it when operating from stored base-unit amounts. Inspect the resolved coin denomination rather than guessing units from a display symbol. Status labels include `active`, `goal-met-pending-settle`, `funded`, and `expired-refunding`; a goal-met projection is not settlement.

**Accounting limitation:** the shipping composition has separate deposit/receipt and progress approvals. The CLI bundles them, but that client-side bundle is not proof of a chain-enforced requirement that every progress update corresponds to a funded deposit. Progress balances alone are therefore insufficient evidence that escrow is fully funded. This catalog does not certify this composition as a trustless refundable pooled-payment solution. That use case requires authoritative backed accounting or another enforceable atomic relationship, with separate validation and testing. Do not silently offer it as a guaranteed refundable variant of PaymentRequestV2.

For an existing collection, inspect actual receipts, progress, escrow, approval conditions, and settlement transactions together. The availability of a refund command does not establish that reserves suffice for all claims. No new escrow or refund primitive is introduced by the payment standards catalog.

See [bounty primitives](https://docs.bitbadges.io/agents/skills/bounty), [crowdfunding primitives](https://docs.bitbadges.io/agents/skills/crowdfund), [coin transfers](https://docs.bitbadges.io/token-standard/approval-criteria/coin-transfers), and [approval trackers](https://docs.bitbadges.io/token-standard/approval-criteria/approval-trackers).

## Bounty JSON

Save the following input as `bounty.json`, replace the demo addresses and metadata, then build it with the CLI command below. `amount` is a display-unit number. `verifier` controls approval evidence, `recipient` receives acceptance funds, and the distinct `submitter` receives deny/expiry refunds. `expiration` is resolved when building; review the emitted timestamp and escrow funding, not just the duration string.

<!-- sdk-example: buildBounty -->
```json
{
  "amount": 5,
  "denom": "BADGE",
  "verifier": "bb1zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zql3w7",
  "recipient": "bb1xvenxvenxvenxvenxvenxvenxvenxvenlrd2nm",
  "submitter": "bb1yg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zda6hxf",
  "expiration": "30d",
  "uri": "https://example.com/metadata.json"
}
```

```bash
bb build bounty --json bounty.json \
  --amount "$(jq -r '.amount' bounty.json)" \
  --denom "$(jq -r '.denom' bounty.json)" \
  --verifier "$(jq -r '.verifier' bounty.json)" \
  --recipient "$(jq -r '.recipient' bounty.json)" \
  --submitter "$(jq -r '.submitter' bounty.json)" \
  --creator "$CREATOR" --output-file bounty-proposal.json
```

The repeated required flags are read from the same JSON file because CLI argument validation runs before loading JSON. Review the resulting proposal using the [CLI lifecycle](https://docs.bitbadges.io/standards/lifecycle). SDK reference: `buildBounty`.

## Crowdfund JSON

Save the following input as `crowdfund.json`, replace the demo addresses and metadata, then build it with the CLI command below. `goal` is a display-unit target and `crowdfunder` is the concrete payout/progress address. `creator` may supply its fallback in the SDK. This is template input, not a guarantee that contribution helpers maintain all accounting correctly; the lifecycle limitations above still apply.

<!-- sdk-example: buildCrowdfund -->
```json
{
  "goal": 100,
  "denom": "BADGE",
  "crowdfunder": "bb1xvenxvenxvenxvenxvenxvenxvenxvenlrd2nm",
  "deadline": "30d",
  "uri": "https://example.com/metadata.json"
}
```

```bash
bb build crowdfund --json crowdfund.json \
  --goal "$(jq -r '.goal' crowdfund.json)" \
  --denom "$(jq -r '.denom' crowdfund.json)" \
  --creator "$CREATOR" --output-file crowdfund-proposal.json
```

The repeated required flags are read from the same JSON file because CLI argument validation runs before loading JSON. Review the resulting proposal using the [CLI lifecycle](https://docs.bitbadges.io/standards/lifecycle). SDK reference: `buildCrowdfund`.