Trust Scoring¶

Trust scoring is the mechanism PrimeStamp uses to quantify confidence in a timestamp's immutability. Each blockchain anchor has a fixed weight reflecting its security properties, and the cumulative score of confirmed anchors is compared against a configurable threshold.

Why Trust Scoring?¶

Different blockchains offer different security guarantees:

Bitcoin has the highest hash rate and longest track record, making its timestamps extremely difficult to forge.
RFC 3161 timestamps are issued by legally recognized authorities and carry weight in court.
Solana is fast but has a smaller validator set and shorter track record.

Rather than treating all anchors equally, PrimeStamp assigns weights so that a Bitcoin anchor counts more toward the trust threshold than a Solana anchor.

Anchor Weights¶

The default trust weights are defined in primestamp.core.models.DEFAULT_TRUST_WEIGHTS:

Anchor Type	Weight	Rationale
Bitcoin	5	Highest security. Largest proof-of-work network, most immutable.
Ethereum	4	Second-largest network. Proof-of-stake with massive validator set.
RFC 3161	4	Legally recognized timestamp authority. Trusted in legal proceedings.
Arweave	3	Permanent storage chain with economic incentive for data permanence.
Base	3	Ethereum L2 (Coinbase). Optimistic rollup inheriting Ethereum security.
Arbitrum One	3	Ethereum L2. Optimistic rollup with mature fraud-proof system.
Optimism	3	Ethereum L2. Optimistic rollup with active Superchain ecosystem.
Polygon	2	Ethereum-adjacent sidechain with periodic checkpointing to Ethereum.
Linea	2	zkEVM L2. Lower weight than optimistic rollups because ecosystem is newer.
Solana	2	Fast L1. Lower weight due to smaller validator economics.
Avalanche	2	Subnet-based L1 with fast finality.
Tezos	2	Proof-of-stake L1 with on-chain governance.
Certificate Transparency	2	Append-only public logs. Auditable but centrally operated.

Chains listed in DEV_PLAN_1 §1.4 (Cardano, NEAR, Hedera, Sui, Aptos, StarkNet) are not yet in the enum — their trust weights land alongside the adapter work in that phase.

Customizing Weights¶

If you disagree with the default weights (or want a stricter configuration for a specific risk tolerance), drop a YAML file at ~/.primestamp/trust_weights.yaml:

# Partial overrides merge on top of defaults.
bitcoin: 6       # Treat Bitcoin anchors as even more secure
ethereum: 5
rfc3161: 5       # Boost legal timestamp authority weight
solana: 1        # Downweight Solana

Anchor names must match the AnchorType enum values (bitcoin, ethereum, solana, polygon, base, arbitrum, optimism, linea, arweave, avalanche, tezos, rfc3161, certificate_transparency). Unknown names are silently ignored.

Set PRIMESTAMP_TRUST_WEIGHTS_PATH to point the loader at an alternate file location for scripted / non-HOME deployments.

How the Score Is Computed¶

The trust score is a computed property on AnchorConfig. It sums the weights of all confirmed anchors:

trust_score = sum(
    weight[anchor.type]
    for anchor in stamp.anchoring.anchors
    if anchor.status == "confirmed"
)

Only anchors with status CONFIRMED count. Anchors that are PENDING, SUBMITTED, or FAILED contribute nothing to the score.

Trust Thresholds¶

The trust threshold is the minimum score required for a stamp to be considered reliably anchored. Each preset sets a different threshold:

Preset	Threshold	Anchors	Max Score	Minimum Confirmations Needed
`casual`	2	Solana (2)	2	Solana must confirm
`standard`	5	Ethereum (4) + Polygon (2)	6	Ethereum must confirm
`archival`	10	Bitcoin (5) + Ethereum (4) + RFC 3161 (4)	13	Any 2 of 3 must confirm
`maximum`	15	Bitcoin (5) + Ethereum (4) + Arweave (3) + RFC 3161 (4) + CT (2)	18	At least 4 of 5 must confirm

The threshold is designed so that:

No single anchor failure makes the archival or maximum presets fall below threshold (except for casual, which uses only one anchor).
Higher-value documents require more independent confirmations.
Legal documents always include RFC 3161 for court admissibility.

Checking Trust Status¶

Python API¶

result = engine.verify_stamp(stamp)

# Trust fields
print(result.trust_score)        # Current score (e.g., 9)
print(result.trust_threshold)    # Required threshold (e.g., 10)
print(result.trust_met)          # True if score >= threshold
print(result.confirmed_anchors)  # Number of confirmed anchors
print(result.pending_anchors)    # Number still pending

Direct from Stamp¶

You can also check trust directly on the stamp's anchoring config, since it uses Pydantic computed fields:

stamp.anchoring.trust_score      # Computed from confirmed anchors
stamp.anchoring.trust_met        # trust_score >= trust_threshold
stamp.anchoring.trust_threshold  # The required minimum

CLI¶

primestamp verify document.stamp.json
# Shows trust score in the verification table:
#   Trust Score  |  Met  |  9/10 (confirmed: 2)

Custom Weights¶

You can override the default weights when creating a stamp by setting trust_weights on the AnchorConfig directly. This is advanced usage for scenarios where you disagree with the default weights or want to prioritize specific chains:

from primestamp.core.models import AnchorConfig, AnchorType

custom_weights = {
    AnchorType.BITCOIN: 10,       # Double Bitcoin's weight
    AnchorType.ETHEREUM: 4,
    AnchorType.RFC3161: 6,        # Boost legal timestamps
    AnchorType.SOLANA: 1,
}

# Apply after stamp creation
stamp.anchoring.trust_weights = custom_weights

Custom weights affect verification

Anyone verifying a stamp will use the weights stored in the stamp. If you change the weights, verifiers will see the same custom weights. Document your rationale for non-default weights.

Examples¶

Freshly Created Stamp¶

A stamp that has just been created has no confirmed anchors yet:

Trust score: 0 / 5
Trust met: False
Confirmed: 0, Pending: 2

This is expected. The stamp is structurally valid (is_valid = True) but not yet fully anchored.

Partially Confirmed¶

After Ethereum confirms but Bitcoin is still pending:

Trust score: 4 / 10
Trust met: False
Confirmed: 1 (Ethereum), Pending: 2 (Bitcoin, RFC 3161)

Fully Confirmed¶

All requested anchors have confirmed:

Trust score: 13 / 10
Trust met: True
Confirmed: 3 (Bitcoin, Ethereum, RFC 3161), Pending: 0

The score exceeds the threshold, confirming maximum reliability for this anchoring configuration.