# Data liquidity and rewards

Testril's data-liquidity model connects paid materialization, titled coverage, subsequent paid reads, and wallet accounting. For agents, the useful questions are: what was bought, what is still covered, what was earned, and what can be claimed?

## Inspect a wallet's accounting

```json
{"tool":"inspect","arguments":{"subject":"nft","wallet":"<WALLET_ADDRESS>"}}
```

The response's `nfts` array has one card per claim-right the wallet holds. Each
card includes its `nft`, `nft_chain_id`, `nft_contract`, `purchases`, and
lifetime totals such as `paid`, `refunded`, `cost`, `earned`, `claimed`,
`unclaimed`, and `pnl`. NFT accounting is the deliberate exception to the
0.9.0 `{atoms, usd}` money object: its monetary values, including `cost`,
`earned`, and signed `pnl`, remain bare decimal strings of USDC atoms. Preserve
exact integer arithmetic. A purchase can appear at payment before data
delivery. Inspect the relevant job and coverage separately.

Each purchase records its quote ID, bound-function ID, original requested window, and accounting. The original window may include blocks already covered even though only unpaid holes were bought. Do not equate requested block count with charged block count.

Purchase earnings and read counts follow the blocks actually delivered. When
historical attribution cannot be reconstructed, a purchase omits `earned`,
`pnl`, and `reads`. On each card, sum known purchase earnings plus
`earned_unattributed` to reconcile lifetime `earned`; missing attribution does
not forfeit unclaimed rewards.

## Data availability is a different ledger

Expiry and materialized geometry live on `inspect subject:bound_function`.
Wallet accounting is not a guarantee that all purchased blocks are currently
available. A purchase is titled before its claim-right mint finishes. During
that interval its card carries `minting: true`; retry inspection until its NFT
is ready.

Cards follow current ownership at the chain tip. The response's `unavailable`
array lists claim-rights on a chain that could not be read as
`{nft, nft_chain_id, reason}` beside cards that were read; it is not a zero
balance. The original payer may no longer hold a claim-right.

## Claim existing rewards

```json
{"tool":"claim_rewards","arguments":{"nft":"<CLAIM_RIGHT_ID>"}}
```

Inspect the selected card's unclaimed amount first. Keep the actual claim
response and re-inspect the wallet afterward. The implementation handles
eligible USDC atoms; it does not promise that a newly bought window will earn
enough to cover its cost.

The minimum claim is 10,000 atoms ($0.01). Below that minimum, the response
reports claimed `"0"`, `reason: "below_minimum"`, and no transfer. A card still
marked `minting: true` returns `claim_right_minting` and pays nothing. Claims
follow current claim-right ownership; an unreadable ownership record is a
refusal, not proof that no rewards exist.

Rewards are paid on the NFT's recorded collection network even when read fees
were paid on other networks. The claim response's `network`, when present,
identifies that payout chain; `claim_rewards` takes no network selector. A
wallet can hold one claim-right per payment chain and can receive more through
on-chain transfers. Its first materialize payment on a payment chain starts a
claim-right there; if the wallet later no longer owns it, its next purchase on
that chain starts another. Keep a pending claim's network during recovery.

## Paid reads and shared value

A paid read of titled coverage can contribute to holder accounting according to the implementation's pricing and overlap rules. A quote alone is not earned revenue. Coverage overlap, retention, prices, and the actual completed paid read matter. Use the current card and settlement records as evidence instead of projecting a yield from a marketing tagline.