Skip to content

Ledger Hold v1

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

Machine-readable schema for one supervised escrow hold on the host-ledger settlement rail.

Governing Basis

Project Lineage

Requirements

Stories

Fields

Field Required Shape Description
schema/v yes const: 1 Schema version.
hold/id yes string Stable identifier of the escrow hold.
contract/id yes string Procurement contract whose settlement path is anchored by this hold.
question/id no string Optional question lifecycle identifier for audit joins.
payer/account-id yes string Ledger account from which value is reserved.
payee/account-id yes string Ledger account eligible to receive release transfers from this hold.
escrow/node-id yes string Supervisory node responsible for maintaining the hold state machine.
escrow-policy/ref no string Escrow policy governing dispute, confirmation, and release behavior for this hold.
amount yes integer Reserved 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 hold in MVP. ORC uses fixed decimal scale 2.
status yes enum: active, disputed, released, partially-released, refunded, expired Operational state of the hold.
created-at yes string Timestamp when the hold was created.
work-by yes string Deadline by which the responder is expected to deliver the work.
accept-by yes string Deadline by which the payer should acknowledge the delivered work.
dispute-by yes string Last moment for opening a valid dispute under the contract policy.
auto-release-after yes string Moment when the hold may be released automatically if prior conditions are satisfied and no dispute is open.
resolved-at no string Timestamp when the hold reached a terminal or review-complete state.
released/amount no integer Amount already released from the hold, expressed in ORC minor units with fixed scale 2.
refunded/amount no integer Amount already refunded from the hold, expressed in ORC minor units with fixed scale 2.
dispute/case-ref no string Formal dispute or arbiter case opened against the hold, if any.
notes no string Optional human-readable notes.
policy_annotations no object

Conditional Rules

Rule 1

When:

{
  "properties": {
    "status": {
      "const": "disputed"
    }
  },
  "required": [
    "status"
  ]
}

Then:

{
  "required": [
    "dispute/case-ref"
  ]
}

Rule 2

When:

{
  "properties": {
    "status": {
      "enum": [
        "released",
        "partially-released",
        "refunded",
        "expired"
      ]
    }
  },
  "required": [
    "status"
  ]
}

Then:

{
  "required": [
    "resolved-at"
  ]
}

Rule 3

When:

{
  "properties": {
    "status": {
      "enum": [
        "released",
        "partially-released"
      ]
    }
  },
  "required": [
    "status"
  ]
}

Then:

{
  "required": [
    "released/amount"
  ]
}

Rule 4

When:

{
  "properties": {
    "status": {
      "const": "refunded"
    }
  },
  "required": [
    "status"
  ]
}

Then:

{
  "required": [
    "refunded/amount"
  ]
}

Rule 5

When:

{
  "required": [
    "escrow/node-id"
  ]
}

Then:

{
  "required": [
    "escrow-policy/ref"
  ]
}

Field Semantics

schema/v

  • Required: yes
  • Shape: const: 1

Schema version.

hold/id

  • Required: yes
  • Shape: string

Stable identifier of the escrow hold.

contract/id

  • Required: yes
  • Shape: string

Procurement contract whose settlement path is anchored by this hold.

question/id

  • Required: no
  • Shape: string

Optional question lifecycle identifier for audit joins.

payer/account-id

  • Required: yes
  • Shape: string

Ledger account from which value is reserved.

payee/account-id

  • Required: yes
  • Shape: string

Ledger account eligible to receive release transfers from this hold.

escrow/node-id

  • Required: yes
  • Shape: string

Supervisory node responsible for maintaining the hold state machine.

escrow-policy/ref

  • Required: no
  • Shape: string

Escrow policy governing dispute, confirmation, and release behavior for this hold.

amount

  • Required: yes
  • Shape: integer

Reserved 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 hold in MVP. ORC uses fixed decimal scale 2.

status

  • Required: yes
  • Shape: enum: active, disputed, released, partially-released, refunded, expired

Operational state of the hold.

created-at

  • Required: yes
  • Shape: string

Timestamp when the hold was created.

work-by

  • Required: yes
  • Shape: string

Deadline by which the responder is expected to deliver the work.

accept-by

  • Required: yes
  • Shape: string

Deadline by which the payer should acknowledge the delivered work.

dispute-by

  • Required: yes
  • Shape: string

Last moment for opening a valid dispute under the contract policy.

auto-release-after

  • Required: yes
  • Shape: string

Moment when the hold may be released automatically if prior conditions are satisfied and no dispute is open.

resolved-at

  • Required: no
  • Shape: string

Timestamp when the hold reached a terminal or review-complete state.

released/amount

  • Required: no
  • Shape: integer

Amount already released from the hold, expressed in ORC minor units with fixed scale 2.

refunded/amount

  • Required: no
  • Shape: integer

Amount already refunded from the hold, expressed in ORC minor units with fixed scale 2.

dispute/case-ref

  • Required: no
  • Shape: string

Formal dispute or arbiter case opened against the hold, if any.

notes

  • Required: no
  • Shape: string

Optional human-readable notes.

policy_annotations

  • Required: no
  • Shape: object