> ## Documentation Index
> Fetch the complete documentation index at: https://docs.presschain.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Canonical Records

> Use source-backed application shapes for Capsules, evidence, contributors and canonical metadata.

# Canonical records

The `presschain-models` repository provides Rust records that are useful at API, projection and integration boundaries. They translate lower-level protocol state into named fields while preserving the identifiers and relationships applications need.

## CapsuleRecord

Current fields include:

```text theme={null}
capsule_id
publisher
outlet_id
content_hash
metadata_hash
metadata_uri
title
summary
canonical_url
cover_url
created_at
updated_at
status
revision_count
exists
```

The model serializes field names in camelCase for JSON.

A projection can use this record to render a Capsule card or article verification page without forcing the client to decode every raw contract tuple.

## EvidenceRecord

Current evidence projections include:

```text theme={null}
evidence_id
capsule_id
evidence_type
label
uri
content_hash
mime_type
metadata_uri
cover_url
submitted_by
is_primary
active
created_at
tally
```

The nested tally contains support, reject and participation counts plus status and finalization state.

## ContributorRecord

Current contributor projections include:

```text theme={null}
contributor_id
capsule_id
wallet
display_name
role
contribution_type
share_bps
attribution_uri
active
created_at
```

Keep `share_bps` as an integer. Convert to a display percentage only at the UI boundary.

## Metadata envelope versus projection record

Canonical Capsule metadata is publication input. It is normalized and hashed before or during publication. `CapsuleRecord` is a read model that may include convenient title, summary, canonical URL and cover fields.

Do not attempt to reproduce an on-chain metadata hash by serializing a transformed projection. Use the canonical metadata envelope and canonicalization rules.

## JavaScript serialization

Large EVM integers and 256-bit identifiers require careful JSON handling. A practical boundary representation is:

```json theme={null}
{
  "capsuleId": "0x0123...64-hex-characters",
  "revisionCount": 3,
  "evidenceId": "42",
  "supportCount": "108"
}
```

Use exact hex strings for bytes32 identifiers and decimal strings for integer quantities that can exceed the safe JavaScript number range.

## Add projection provenance

When an API must be auditable, attach chain coordinates beside the semantic record:

```ts theme={null}
type Projected<T> = {
  data: T;
  chain: {
    blockNumber: string;
    blockHash: string;
    transactionHash?: string;
  };
};
```

This keeps domain models clean while still allowing consumers to trace a projected fact back to network state.

## Compatibility discipline

Treat changes to canonical records as versioned API changes when they affect serialized shape or meaning. Adding a convenience UI field and changing the semantics of `status` are not equivalent changes.

A strong projection layer makes those distinctions explicit instead of depending on every client to infer them.