Skip to content

Ledger Account v1

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

Machine-readable schema for one supervised prepaid ledger account used by the host-ledger settlement rail.

Governing Basis

Project Lineage

Requirements

Stories

Fields

Field Required Shape Description
schema/v yes const: 1 Schema version.
account/id yes string Stable identifier of the supervised ledger account.
account/purpose yes enum: participant-settlement, pod-user-settlement, org-settlement, community-pool Operational purpose of the account within the host-ledger rail.
owner/kind yes enum: participant, pod-user, org Identity layer that owns the account.
owner/id yes string Canonical identifier of the account owner. The allowed format depends on owner/kind.
federation/id yes string Authoritative federation ledger scope for this account.
unit yes const: ORC Internal settlement unit carried by this account in MVP. ORC uses fixed decimal scale 2; protocol-visible integer balances therefore carry ORC minor units.
status yes enum: active, suspended, closed Administrative state of the account on the supervised ledger.
available/balance no integer Optional exported read-model snapshot of immediately spendable balance in ORC minor units with fixed scale 2. The append-only transfer and hold facts remain the source of truth.
held/balance no integer Optional exported read-model snapshot of funds currently reserved by active holds in ORC minor units with fixed scale 2.
created-at yes string Timestamp when the account was opened.
closed-at no string Timestamp when the account was closed, if applicable.
gateway/ref no string Optional reference to the gateway or onboarding policy under which the account was provisioned.
disbursement/controller-kind no enum: owner, council Who is allowed to authorize outbound disbursement from this account.
disbursement/controller-id no string Canonical identifier of the disbursement controller when it differs from the owner.
policy_annotations no object

Conditional Rules

Rule 1

When:

{
  "properties": {
    "account/purpose": {
      "const": "community-pool"
    }
  },
  "required": [
    "account/purpose"
  ]
}

Then:

{
  "properties": {
    "owner/kind": {
      "const": "org"
    },
    "disbursement/controller-kind": {
      "const": "council"
    },
    "disbursement/controller-id": {
      "pattern": "^council:did:key:z[1-9A-HJ-NP-Za-km-z]+$"
    }
  },
  "required": [
    "disbursement/controller-kind",
    "disbursement/controller-id"
  ]
}

Rule 2

When:

{
  "properties": {
    "owner/kind": {
      "const": "participant"
    }
  },
  "required": [
    "owner/kind"
  ]
}

Then:

{
  "properties": {
    "owner/id": {
      "pattern": "^participant:did:key:z[1-9A-HJ-NP-Za-km-z]+$"
    }
  }
}

Rule 3

When:

{
  "properties": {
    "owner/kind": {
      "const": "pod-user"
    }
  },
  "required": [
    "owner/kind"
  ]
}

Then:

{
  "properties": {
    "owner/id": {
      "pattern": "^pod-user:did:key:z[1-9A-HJ-NP-Za-km-z]+$"
    }
  }
}

Rule 4

When:

{
  "properties": {
    "owner/kind": {
      "const": "org"
    }
  },
  "required": [
    "owner/kind"
  ]
}

Then:

{
  "properties": {
    "owner/id": {
      "pattern": "^org:did:key:z[1-9A-HJ-NP-Za-km-z]+$"
    }
  }
}

Rule 5

When:

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

Then:

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

Field Semantics

schema/v

  • Required: yes
  • Shape: const: 1

Schema version.

account/id

  • Required: yes
  • Shape: string

Stable identifier of the supervised ledger account.

account/purpose

  • Required: yes
  • Shape: enum: participant-settlement, pod-user-settlement, org-settlement, community-pool

Operational purpose of the account within the host-ledger rail.

owner/kind

  • Required: yes
  • Shape: enum: participant, pod-user, org

Identity layer that owns the account.

owner/id

  • Required: yes
  • Shape: string

Canonical identifier of the account owner. The allowed format depends on owner/kind.

federation/id

  • Required: yes
  • Shape: string

Authoritative federation ledger scope for this account.

unit

  • Required: yes
  • Shape: const: ORC

Internal settlement unit carried by this account in MVP. ORC uses fixed decimal scale 2; protocol-visible integer balances therefore carry ORC minor units.

status

  • Required: yes
  • Shape: enum: active, suspended, closed

Administrative state of the account on the supervised ledger.

available/balance

  • Required: no
  • Shape: integer

Optional exported read-model snapshot of immediately spendable balance in ORC minor units with fixed scale 2. The append-only transfer and hold facts remain the source of truth.

held/balance

  • Required: no
  • Shape: integer

Optional exported read-model snapshot of funds currently reserved by active holds in ORC minor units with fixed scale 2.

created-at

  • Required: yes
  • Shape: string

Timestamp when the account was opened.

closed-at

  • Required: no
  • Shape: string

Timestamp when the account was closed, if applicable.

gateway/ref

  • Required: no
  • Shape: string

Optional reference to the gateway or onboarding policy under which the account was provisioned.

disbursement/controller-kind

  • Required: no
  • Shape: enum: owner, council

Who is allowed to authorize outbound disbursement from this account.

disbursement/controller-id

  • Required: no
  • Shape: string

Canonical identifier of the disbursement controller when it differs from the owner.

policy_annotations

  • Required: no
  • Shape: object