Ledger Transfer v1

Source schema: doc/schemas/ledger-transfer.v1.schema.json

Machine-readable schema for one append-only internal transfer recorded by the host-ledger settlement rail.

Governing Basis

• doc/project/40-proposals/016-supervised-prepaid-gateway-and-escrow-mvp.md
• doc/project/50-requirements/requirements-007.md

Project Lineage

Requirements

• doc/project/50-requirements/requirements-006.md
• doc/project/50-requirements/requirements-007.md

Stories

• doc/project/30-stories/story-001.md
• doc/project/30-stories/story-004.md

Fields

Field	Required	Shape	Description
schema/v	yes	const: 1	Schema version.
transfer/id	yes	string	Stable identifier of the append-only transfer fact.
kind	yes	enum: top-up-credit, escrow-hold, release, partial-release, refund, payout-debit, adjustment	Transfer class on the supervised ledger.
from/account-id	yes	string	Debited ledger account identifier.
to/account-id	yes	string	Credited ledger account identifier.
amount	yes	integer	Transferred amount in internal minor units. For ORC, the value uses ORC minor units with fixed scale 2.
unit	yes	const: ORC	Internal settlement unit carried by the transfer in MVP. ORC uses fixed decimal scale 2.
created-at	yes	string	Timestamp when the transfer fact was recorded.
hold/id	no	string	Escrow hold to which the transfer belongs, when applicable.
contract/id	no	string	Procurement contract driving the transfer, when applicable.
gateway-receipt/id	no	string	Gateway receipt that justified the transfer, when applicable.
notes	no	string	Optional human-readable notes.
policy_annotations	no	object

Conditional Rules

Rule 1

When:

{
  "properties": {
    "kind": {
      "enum": [
        "escrow-hold",
        "release",
        "partial-release",
        "refund"
      ]
    }
  },
  "required": [
    "kind"
  ]
}

Then:

{
  "required": [
    "hold/id",
    "contract/id"
  ]
}

Rule 2

When:

{
  "properties": {
    "kind": {
      "enum": [
        "top-up-credit",
        "payout-debit"
      ]
    }
  },
  "required": [
    "kind"
  ]
}

Then:

{
  "required": [
    "gateway-receipt/id"
  ]
}

Field Semantics

schema/v

• Required: yes
• Shape: const: 1

Schema version.

transfer/id

• Required: yes
• Shape: string

Stable identifier of the append-only transfer fact.

kind

• Required: yes
• Shape: enum: top-up-credit, escrow-hold, release, partial-release, refund, payout-debit, adjustment

Transfer class on the supervised ledger.

from/account-id

• Required: yes
• Shape: string

Debited ledger account identifier.

to/account-id

• Required: yes
• Shape: string

Credited ledger account identifier.

amount

• Required: yes
• Shape: integer

Transferred amount in internal minor units. For ORC, the value uses ORC minor units with fixed scale 2.

unit

• Required: yes
• Shape: const: ORC

Internal settlement unit carried by the transfer in MVP. ORC uses fixed decimal scale 2.

created-at

• Required: yes
• Shape: string

Timestamp when the transfer fact was recorded.

hold/id

• Required: no
• Shape: string

Escrow hold to which the transfer belongs, when applicable.

contract/id

• Required: no
• Shape: string

Procurement contract driving the transfer, when applicable.

gateway-receipt/id

• Required: no
• Shape: string

Gateway receipt that justified the transfer, when applicable.

notes

• Required: no
• Shape: string

Optional human-readable notes.

policy_annotations

• Required: no
• Shape: object