Skip to content

Gateway Policy v1

Source schema: doc/schemas/gateway-policy.v1.schema.json

Machine-readable schema for one trusted gateway policy binding a servicing node to an accountable organization in the host-ledger settlement rail.

Governing Basis

Project Lineage

Requirements

Stories

Fields

Field Required Shape Description
schema/v yes const: 1 Schema version.
policy/id yes string Stable identifier of the gateway policy.
created-at yes string Timestamp when the gateway policy became auditable.
federation/id yes string Federation scope in which the gateway policy applies.
gateway/node-id yes string Node currently serving the trusted gateway role under this policy.
operator/org-ref yes string Accountable organization operating the gateway policy.
settlement/unit yes const: ORC Internal settlement unit handled by this gateway policy in MVP.
supported/directions yes array Permitted directions for fiat-to-credit or credit-to-fiat boundary crossings.
kyc/mode no enum: none, provider-managed, manual-review High-level compliance posture applied to payout or top-up flows.
payout/manual-review no boolean Whether outbound settlement may require manual review under this policy.
external/providers no array Named external payment providers or rails admitted under this policy.
fee/ingress-basis-points yes integer Fixed ingress fee rate applied on gross external top-up amount in basis points (100 = 1.00%).
fee/ingress-destination-account-id yes string Ledger account that receives ingress fee credits, typically the community-pool.
fee/ingress-min-internal-amount yes integer Minimum internal-equivalent amount below which ingress fee is not applied.
fee/egress-basis-points yes integer | null Optional payout-side fee rate in basis points (100 = 1.00%). MVP keeps this null until outbound payout stabilizes.
status yes enum: active, suspended, retired Administrative lifecycle state of the gateway policy.
suspended-at no string Timestamp when the gateway policy was suspended, if applicable.
retired-at no string Timestamp when the gateway policy was retired, if applicable.
notes no string Optional human-readable notes.
policy_annotations no object

Conditional Rules

Rule 1

When:

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

Then:

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

Rule 2

When:

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

Then:

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

Field Semantics

schema/v

  • Required: yes
  • Shape: const: 1

Schema version.

policy/id

  • Required: yes
  • Shape: string

Stable identifier of the gateway policy.

created-at

  • Required: yes
  • Shape: string

Timestamp when the gateway policy became auditable.

federation/id

  • Required: yes
  • Shape: string

Federation scope in which the gateway policy applies.

gateway/node-id

  • Required: yes
  • Shape: string

Node currently serving the trusted gateway role under this policy.

operator/org-ref

  • Required: yes
  • Shape: string

Accountable organization operating the gateway policy.

settlement/unit

  • Required: yes
  • Shape: const: ORC

Internal settlement unit handled by this gateway policy in MVP.

supported/directions

  • Required: yes
  • Shape: array

Permitted directions for fiat-to-credit or credit-to-fiat boundary crossings.

kyc/mode

  • Required: no
  • Shape: enum: none, provider-managed, manual-review

High-level compliance posture applied to payout or top-up flows.

payout/manual-review

  • Required: no
  • Shape: boolean

Whether outbound settlement may require manual review under this policy.

external/providers

  • Required: no
  • Shape: array

Named external payment providers or rails admitted under this policy.

fee/ingress-basis-points

  • Required: yes
  • Shape: integer

Fixed ingress fee rate applied on gross external top-up amount in basis points (100 = 1.00%).

fee/ingress-destination-account-id

  • Required: yes
  • Shape: string

Ledger account that receives ingress fee credits, typically the community-pool.

fee/ingress-min-internal-amount

  • Required: yes
  • Shape: integer

Minimum internal-equivalent amount below which ingress fee is not applied.

fee/egress-basis-points

  • Required: yes
  • Shape: integer | null

Optional payout-side fee rate in basis points (100 = 1.00%). MVP keeps this null until outbound payout stabilizes.

status

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

Administrative lifecycle state of the gateway policy.

suspended-at

  • Required: no
  • Shape: string

Timestamp when the gateway policy was suspended, if applicable.

retired-at

  • Required: no
  • Shape: string

Timestamp when the gateway policy was retired, if applicable.

notes

  • Required: no
  • Shape: string

Optional human-readable notes.

policy_annotations

  • Required: no
  • Shape: object