dev.cocore.account.tokenPatronage

{
  "$type": "com.atproto.lexicon.schema",
  "defs": {
    "main": {
      "key": "tid",
      "record": {
        "properties": {
          "createdAt": {
            "format": "datetime",
            "type": "string"
          },
          "exchange": {
            "description": "Exchange DID. MUST equal the repo this record is published in.",
            "format": "did",
            "type": "string"
          },
          "patronageScore": {
            "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).",
            "minimum": 0,
            "type": "integer"
          },
          "period": {
            "description": "Rebate period [start, end). Receipts whose `completedAt` falls in this window contributed to the patronage tally.",
            "ref": "#period",
            "type": "ref"
          },
          "policy": {
            "description": "Strong-ref to the exchangePolicy in effect at distribution time. Pins `patronageDistribution.fractionBps` + `treasuryDid` so the rebate math is reproducible offline.",
            "ref": "com.atproto.repo.strongRef",
            "type": "ref"
          },
          "recipient": {
            "description": "DID receiving the patronage rebate.",
            "format": "did",
            "type": "string"
          },
          "tokensCredited": {
            "description": "Tokens debited from the treasury and credited to the recipient.",
            "minimum": 1,
            "type": "integer"
          },
          "totalPatronage": {
            "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)`.",
            "minimum": 0,
            "type": "integer"
          },
          "treasuryBefore": {
            "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.",
            "minimum": 0,
            "type": "integer"
          }
        },
        "required": [
          "exchange",
          "recipient",
          "period",
          "patronageScore",
          "totalPatronage",
          "tokensCredited",
          "treasuryBefore",
          "policy",
          "createdAt"
        ],
        "type": "object"
      },
      "type": "record"
    },
    "period": {
      "description": "Half-open interval [start, end). Closed-loop cocore.dev uses calendar months in UTC by default.",
      "properties": {
        "end": {
          "format": "datetime",
          "type": "string"
        },
        "start": {
          "format": "datetime",
          "type": "string"
        }
      },
      "required": [
        "start",
        "end"
      ],
      "type": "object"
    }
  },
  "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.",
  "id": "dev.cocore.account.tokenPatronage",
  "lexicon": 1
}