# dev.cocore.account.tokenPatronage

> Published by [cocore.dev](https://lexicon.garden/identity/did:plc:5quuhkmwe2q4k3azfsgg7kdz)

✓ This is the authoritative definition for this NSID.

## Description

Records a patronage rebate: a periodic distribution of treasury balance back to an active member in proportion to their patronage (consumer spending + provider earnings) during the rebate period. Written by the exchange to its own PDS when the distribution fires. One record per (recipient, period) pair — the exchange MUST NOT distribute twice for the same (recipient, period). Direct analog of REI's annual member dividend or a credit union's quarterly capital credit: every term is visible, the math is the same for every member, and the distribution is rule-based rather than discretionary. Receipts of work + this record together let a member reconstruct every CC their balance has touched.

## Links

- [View on Lexicon Garden](https://lexicon.garden/lexicon/did:plc:5quuhkmwe2q4k3azfsgg7kdz/dev.cocore.account.tokenPatronage)
- [Documentation](https://lexicon.garden/lexicon/did:plc:5quuhkmwe2q4k3azfsgg7kdz/dev.cocore.account.tokenPatronage/docs)
- [Examples](https://lexicon.garden/lexicon/did:plc:5quuhkmwe2q4k3azfsgg7kdz/dev.cocore.account.tokenPatronage/examples)

## Definitions

### `dev.cocore.account.tokenPatronage`

**Type**: `record`

**Key**: `tid`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `period` | `ref` → `#period` | Yes | Rebate period [start, end). Receipts whose `completedAt` falls in this window contributed to the patronage tally. |
| `policy` | `ref` → `com.atproto.repo.strongRef` | Yes | Strong-ref to the exchangePolicy in effect at distribution time. Pins `patronageDistribution.fractionBps` + `treasuryDid` so the rebate math is reproducible offline. |
| `exchange` | `string` (did) | Yes | Exchange DID. MUST equal the repo this record is published in. |
| `createdAt` | `string` (datetime) | Yes |  |
| `recipient` | `string` (did) | Yes | DID receiving the patronage rebate. |
| `patronageScore` | `integer` | Yes | This recipient's patronage during the period — tokens spent as requester PLUS tokens earned as provider. Self-loop receipts count once (the doc's `selfLoop.feeWaived` already handles the fee carve-out). |
| `tokensCredited` | `integer` | Yes | Tokens debited from the treasury and credited to the recipient. |
| `totalPatronage` | `integer` | Yes | Sum of all participating DIDs' patronage scores during the period. Lets a verifier reproduce the rebate share: `tokensCredited = floor(treasuryBefore * fractionBps / 10000 * patronageScore / totalPatronage)`. |
| `treasuryBefore` | `integer` | Yes | Treasury balance immediately before this distribution period fired. Pinned for audit so verifiers can sum the per-recipient `tokensCredited` and confirm it equals `floor(treasuryBefore * fractionBps / 10000)` modulo rounding. |

### `dev.cocore.account.tokenPatronage#period`

**Type**: `object`

Half-open interval [start, end). Closed-loop cocore.dev uses calendar months in UTC by default.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `end` | `string` (datetime) | Yes |  |
| `start` | `string` (datetime) | Yes |  |

## Raw Schema

```json
{
  "id": "dev.cocore.account.tokenPatronage",
  "defs": {
    "main": {
      "key": "tid",
      "type": "record",
      "record": {
        "type": "object",
        "required": [
          "exchange",
          "recipient",
          "period",
          "patronageScore",
          "totalPatronage",
          "tokensCredited",
          "treasuryBefore",
          "policy",
          "createdAt"
        ],
        "properties": {
          "period": {
            "ref": "#period",
            "type": "ref",
            "description": "Rebate period [start, end). Receipts whose `completedAt` falls in this window contributed to the patronage tally."
          },
          "policy": {
            "ref": "com.atproto.repo.strongRef",
            "type": "ref",
            "description": "Strong-ref to the exchangePolicy in effect at distribution time. Pins `patronageDistribution.fractionBps` + `treasuryDid` so the rebate math is reproducible offline."
          },
          "exchange": {
            "type": "string",
            "format": "did",
            "description": "Exchange DID. MUST equal the repo this record is published in."
          },
          "createdAt": {
            "type": "string",
            "format": "datetime"
          },
          "recipient": {
            "type": "string",
            "format": "did",
            "description": "DID receiving the patronage rebate."
          },
          "patronageScore": {
            "type": "integer",
            "minimum": 0,
            "description": "This recipient's patronage during the period — tokens spent as requester PLUS tokens earned as provider. Self-loop receipts count once (the doc's `selfLoop.feeWaived` already handles the fee carve-out)."
          },
          "tokensCredited": {
            "type": "integer",
            "minimum": 1,
            "description": "Tokens debited from the treasury and credited to the recipient."
          },
          "totalPatronage": {
            "type": "integer",
            "minimum": 0,
            "description": "Sum of all participating DIDs' patronage scores during the period. Lets a verifier reproduce the rebate share: `tokensCredited = floor(treasuryBefore * fractionBps / 10000 * patronageScore / totalPatronage)`."
          },
          "treasuryBefore": {
            "type": "integer",
            "minimum": 0,
            "description": "Treasury balance immediately before this distribution period fired. Pinned for audit so verifiers can sum the per-recipient `tokensCredited` and confirm it equals `floor(treasuryBefore * fractionBps / 10000)` modulo rounding."
          }
        }
      }
    },
    "period": {
      "type": "object",
      "required": [
        "start",
        "end"
      ],
      "properties": {
        "end": {
          "type": "string",
          "format": "datetime"
        },
        "start": {
          "type": "string",
          "format": "datetime"
        }
      },
      "description": "Half-open interval [start, end). Closed-loop cocore.dev uses calendar months in UTC by default."
    }
  },
  "$type": "com.atproto.lexicon.schema",
  "lexicon": 1,
  "description": "Records a patronage rebate: a periodic distribution of treasury balance back to an active member in proportion to their patronage (consumer spending + provider earnings) during the rebate period. Written by the exchange to its own PDS when the distribution fires. One record per (recipient, period) pair — the exchange MUST NOT distribute twice for the same (recipient, period). Direct analog of REI's annual member dividend or a credit union's quarterly capital credit: every term is visible, the math is the same for every member, and the distribution is rule-based rather than discretionary. Receipts of work + this record together let a member reconstruct every CC their balance has touched."
}
```