# PIP-0012 · RWA: the claim and its representations

An optional instrument on a capability names the real-world claim. The capability remains one representation, on one rail.

## Why

A capability names a representation: fiat on a rail, or a token on a chain ([PIP-0006](/pips/0006)). A treasury token and a book entry at its issuer can be the same claim. The capability does not say so. A receipt that sends the token and receives fiat then has the same shape as an exchange.

This PIP names the claim. A real-world asset (RWA) is that claim. The capability stays one representation of it, on one rail.

## What an RWA is

| Term | Meaning |
|---|---|
| Instrument | The claim. An issuer and an identifier. Independent of any rail. |
| Representation | How that claim appears on one rail. This is the capability: a token on a chain, or fiat on `book` or another rail. |

Across two networks, a representation moves, or one representation is retired and another is issued. The underlying stays with the issuer. PATH carries the signed statement. It does not hold the asset.

`asset_type` stays `fiat` or `token`. An RWA is not a third asset type and not a rail.

## The field

`instrument` is optional on a capability. Absent, the capability is unchanged: the asset is the fiat currency or the token.

```json
{
  "rail": "blockchain",
  "chain": { "slug": "base", "caip2": "eip155:8453" },
  "asset_type": "token",
  "asset_code": "TBILL",
  "standard": "erc20",
  "contract": "0x1111111111111111111111111111111111111111",
  "instrument": { "issuer": "member-a", "id": "tbill-2026-03" }
}
```

```json
{
  "rail": "book",
  "asset_type": "fiat",
  "asset_code": "USD",
  "instrument": { "issuer": "member-a", "id": "tbill-2026-03" }
}
```

The two capabilities above are two representations of one claim. An address that accepts both lists both.

| Field | Rule |
|---|---|
| `issuer` | Required with `id`. When the issuer is a PATH member, the member slug. Otherwise a string the signer chooses. |
| `id` | Required with `issuer`. The issuer's identifier for the claim. |
| Together | Both present, or the whole `instrument` omitted. Never `null`. |
| Length | Each value is 1 to 128 characters, with no leading or trailing space. |

## Where it appears

A capability carries it, so the existing objects carry it in the same place:

| Object | Field |
|---|---|
| Standing intent | `accepts[]` |
| Payment request | `accepts[]`, frozen at issue |
| Payment instruction | `via` |
| Receipt | `via` |

`sent` and `received` stay amounts. They do not carry `instrument`. When they differ, `fx` stays required ([PIP-0011](/pips/0011)). This PIP does not redefine exchange. A reader that sees the same `instrument` on two capabilities may treat them as one claim. PATH does not pair the receipts: the parties match them by `instruction`, `rail_references`, or an attestation, as in PIP-0011.

## Statement

`instrument` is part of the signed object. It states which claim the signer means. PATH does not resolve `issuer`, does not keep a register of instruments, and does not check that a contract belongs to that issuer.

## What stays unchanged

- One capability is one rail and one asset.
- On `book`, the asset stays `fiat` ([PIP-0007](/pips/0007)).
- `route` stays `null`. Its shape is [PIP-0005](/pips/0005). Filling it is still [PIP-0004](/pips/0004).
- PATH does not set a price, take custody, or transfer title. Classification of the instrument stays with the operator.

## Canonical form

These rules apply before any digest or signature, with the rules of [PIP-0006](/pips/0006).

| Element | Rule |
|---|---|
| Absent `instrument` | Omitted. Never `null`. |
| `issuer`, `id` | Strings, as in the table above. Not normalised beyond trimming. |
| Order | `issuer`, then `id`. |
| `grammar` | An object that carries `instrument` states `grammar: 3`. |

A `grammar: 2` object omits `instrument`. A reader does not treat it as naming a claim.

## Until this is implemented

Implementations omit `instrument` and emit `grammar: 2`. A `grammar: 3` object is defined here and is not part of the current version.