# dev.malpercio.cards.witness

> Published by [cards.malpercio.dev](https://lexicon.garden/identity/did:plc:kmg2eqexpdefljft34crzesc)

✓ This is the authoritative definition for this NSID.

## Links

- [View on Lexicon Garden](https://lexicon.garden/lexicon/did:plc:kmg2eqexpdefljft34crzesc/dev.malpercio.cards.witness)
- [Documentation](https://lexicon.garden/lexicon/did:plc:kmg2eqexpdefljft34crzesc/dev.malpercio.cards.witness/docs)
- [Examples](https://lexicon.garden/lexicon/did:plc:kmg2eqexpdefljft34crzesc/dev.malpercio.cards.witness/examples)

## Definitions

### `dev.malpercio.cards.witness`

**Type**: `record`

An appview's signed observation of a card changing hands, written into the appview's own repo. Triggered by a dev.malpercio.cards.item appearing on the firehose. Accepted witnesses form a prev-linked chain per give; exactly one accepted witness exists per (give, hop). Rejected witnesses explain why a claimant's item is not recognized. The chain is durable against player-side deletions and auditable by replaying the firehose.

**Key**: `tid`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `detail` | `string` | No | Rejected only. Human-readable specifics, e.g. the URI of the item that won. |
| `from` | `string` (did) | No | Sender of the transfer, if any. |
| `give` | `string` (at-uri) | Yes | Root give this observation concerns. |
| `holder` | `string` (did) | Yes | Repo owner of item. For accepted witnesses, the recognized holder after this hop. |
| `hop` | `integer` | No | Accepted only. 0 = received from provider, n = nth transfer. |
| `item` | `ref` → `com.atproto.repo.strongRef` | Yes | The claimant's item as seen. Pinned so the observation stands even if the item is later deleted. |
| `prev` | `ref` → `com.atproto.repo.strongRef` | No | Accepted only. The accepted witness for hop-1. |
| `reason` | `string` | No | Rejected only. superseded: another item was already accepted at this hop. not-holder: the transfer's sender was not the recognized holder. expired: transfer.expiresAt passed before the item appeared. invalid: the records fail structural verification (recipient, CID, revoked give). |
| `seenAt` | `string` (datetime) | Yes |  |
| `status` | `string` | Yes |  |
| `transfer` | `ref` → `com.atproto.repo.strongRef` | No | The transfer as seen, absent at hop 0. |

## Raw Schema

```json
{
  "$type": "com.atproto.lexicon.schema",
  "defs": {
    "main": {
      "description": "An appview's signed observation of a card changing hands, written into the appview's own repo. Triggered by a dev.malpercio.cards.item appearing on the firehose. Accepted witnesses form a prev-linked chain per give; exactly one accepted witness exists per (give, hop). Rejected witnesses explain why a claimant's item is not recognized. The chain is durable against player-side deletions and auditable by replaying the firehose.",
      "key": "tid",
      "record": {
        "properties": {
          "detail": {
            "description": "Rejected only. Human-readable specifics, e.g. the URI of the item that won.",
            "maxLength": 512,
            "type": "string"
          },
          "from": {
            "description": "Sender of the transfer, if any.",
            "format": "did",
            "type": "string"
          },
          "give": {
            "description": "Root give this observation concerns.",
            "format": "at-uri",
            "type": "string"
          },
          "holder": {
            "description": "Repo owner of item. For accepted witnesses, the recognized holder after this hop.",
            "format": "did",
            "type": "string"
          },
          "hop": {
            "description": "Accepted only. 0 = received from provider, n = nth transfer.",
            "minimum": 0,
            "type": "integer"
          },
          "item": {
            "description": "The claimant's item as seen. Pinned so the observation stands even if the item is later deleted.",
            "ref": "com.atproto.repo.strongRef",
            "type": "ref"
          },
          "prev": {
            "description": "Accepted only. The accepted witness for hop-1.",
            "ref": "com.atproto.repo.strongRef",
            "type": "ref"
          },
          "reason": {
            "description": "Rejected only. superseded: another item was already accepted at this hop. not-holder: the transfer's sender was not the recognized holder. expired: transfer.expiresAt passed before the item appeared. invalid: the records fail structural verification (recipient, CID, revoked give).",
            "knownValues": [
              "superseded",
              "not-holder",
              "expired",
              "invalid"
            ],
            "type": "string"
          },
          "seenAt": {
            "format": "datetime",
            "type": "string"
          },
          "status": {
            "knownValues": [
              "accepted",
              "rejected"
            ],
            "type": "string"
          },
          "transfer": {
            "description": "The transfer as seen, absent at hop 0.",
            "ref": "com.atproto.repo.strongRef",
            "type": "ref"
          }
        },
        "required": [
          "give",
          "item",
          "holder",
          "status",
          "seenAt"
        ],
        "type": "object"
      },
      "type": "record"
    }
  },
  "id": "dev.malpercio.cards.witness",
  "lexicon": 1
}
```