What are PayNotes?

1. Introduction & Overview

The PayNote is a standard Blue document that represents a commitment of value from a Payer to a Payee, arbitrated and secured by a trusted Guarantor. It is not just a record of a transaction; it is a live, stateful, and programmable document that manages the entire lifecycle of a value exchange, from authorization and reservation to final capture or release.

By modeling payments and value commitments as verifiable, event-driven documents, the PayNote provides a level of transparency, security, and flexibility that is difficult to achieve with traditional APIs. It creates a "chain of evidence" for every step of the process, which can be independently verified by all participants.

2. Core Concepts

The Three Participants

Every PayNote has three core roles, represented by channels in the document:

Payer: The party providing the funds or value. The Payer initiates the PayNote and authorizes the use of their resources.
Payee: The party intended to receive the funds or value. The Payee is often the one who triggers the final capture of funds.
Guarantor: The trusted entity that controls the underlying funds or value (e.g., a bank, a credit card processor, a platform like a restaurant for a voucher). The Guarantor is the ultimate source of truth; it is the only participant with the authority to emit events that formally change the PayNote's state (e.g., Funds Reserved, Funds Captured).

The Event-Driven Lifecycle

A PayNote evolves through a series of states. Participants (Payer or Payee) trigger Requests (e.g., Capture Funds Requested), and the Guarantor responds by emitting definitive, strongly-typed Events (e.g., Funds Captured or Capture Declined). This creates a decoupled, asynchronous flow where all state changes are explicit, auditable facts recorded on a timeline.

Child PayNotes: Subdividing Value

A key feature of the PayNote is its ability to issue Child PayNotes. A Payer can reserve a larger sum in a parent PayNote (e.g., $500) and then grant an agent or another person the ability to issue smaller, independent PayNotes that draw from this reserved amount.

When a Child PayNote is captured, the funds are transferred by the Guarantor, and the reserved amount on the parent is reduced.
When a Child PayNote is released or expires, the value returns to the parent PayNote's reserved pool.

3. The Base `PayNote` Definition

This is the foundational Blue document type for a PayNote. It defines the core state fields, the participants, and the operations the Guarantor can use to emit status-changing events.

name: PayNote
description: A verifiable instrument for managing a commitment of value between a Payer, Payee, and Guarantor.

# --- Core State Fields ---
status:
  description: The current state of the PayNote (e.g., Pending, Approved, Reserved, Captured, Released, Rejected).
  type: Text
  value: Pending
currency:
  description: The ISO 4217 currency code for the transaction.
  type: Text
amount:
  description: The amounts associated with this PayNote.
  total:
    description: The maximum total value of this PayNote.
    type: Integer # Stored in minor units (e.g., cents)
  reserved:
    description: The amount currently reserved by the Guarantor.
    type: Integer
    value: 0
  captured:
    description: The amount that has been successfully captured.
    type: Integer
    value: 0
payNoteInitialStateDescription:
  summary:
    type: Text
    description: |
      General information about the PayNote. It should capture the most important
      information, most critical or non-standard elements should be covered here.
      Markdown format suggested.
  details:
    type: Text
    description: |
      Complete text description of the PayNote, with everything significant explained.
      Markdown format suggested.

# --- Participants & Contracts ---
contracts:
  payerChannel:
    type: MyOS Timeline
  payeeChannel:
    type: MyOS Timeline
  guarantorChannel:
    type: MyOS Timeline

  # --- Operations for the Guarantor to emit state-changing events ---
  # Each operation is restricted to the guarantorChannel. When called, it simply
  # triggers a corresponding event that all participants can observe.

  approvePayNote:
    type: Operation
    channel: guarantorChannel
    # ... implementation triggers 'PayNote Approved' event ...

  rejectPayNote:
    type: Operation
    channel: guarantorChannel
    # ... implementation triggers 'PayNote Rejected' event ...

  specifySettlementAmount:
    type: Operation
    channel: guarantorChannel
    request: { type: Integer } # The final amount
    # ... implementation triggers 'Settlement Amount Specified' event ...
  
  # ... and so on for all other Guarantor-driven events ...

4. PayNote Events (The Guarantor's Vocabulary)

These are the official, state-changing events that can only be emitted by the Guarantor.

Lifecycle Events

name: PayNote Approved
type: Response
description: The Guarantor confirms the PayNote is valid and ready for further action.
---
name: PayNote Rejected
type: Response
description: The Guarantor denies the creation of the PayNote.
reason:
  type: Text
---
name: PayNote Cancelled
type: Response
description: The Guarantor confirms PayNote cancellation requested by Payer.
---
name: PayNote Cancellation Rejected
type: Response
description: The Guarantor denies PayNote cancellation requested by Payer.
reason:
  type: Text

Reservation Events

name: Funds Reserved
type: Response
description: The Guarantor confirms that funds have been successfully reserved (held).
amountReserved:
  type: Integer
---
name: Reservation Declined
type: Response
description: The Guarantor could not reserve the requested funds.
reason:
  type: Text
---
name: Reservation Released
type: Response
description: The Guarantor confirms that previously reserved funds have been released.
amountReleased:
  type: Integer
---
name: Reservation Release Declined
type: Response
description: The Guarantor failed to release the reserved funds.
reason:
  type: Text

Capture Events

name: Funds Captured
type: Response
description: The Guarantor confirms that funds have been successfully transferred to the Payee.
amountCaptured:
  type: Integer
---
name: Capture Declined
type: Response
description: The Guarantor declined the capture request before attempting the transfer.
reason:
  type: Text
---
name: Capture Failed
type: Response
description: The Guarantor attempted the transfer, but it failed for a technical reason.
reason:
  type: Text

Settlement & Child PayNote Events

name: Settlement Amount Specified
type: Response
description: The Guarantor confirms the final settlement amount, which may differ from the initial total.
finalAmount:
  type: Integer
---
name: Settlement Amount Rejected
type: Response
description: The Guarantor rejects the proposed settlement amount.
reason:
  type: Text
---
name: Child PayNote Issued
type: Response
description: The Guarantor confirms that a new Child PayNote has been issued against this parent.
childPayNote:
  description: Content of the issued PayNote
---
name: Child PayNote Issuance Declined
type: Response
description: The Guarantor declined the request to issue a Child PayNote.
reason:
  type: Text

5. PayNote Requests (The Participant's Vocabulary)

These are the events that the Payer or Payee can trigger to request an action from the Guarantor.

name: Payee Assignment Requested
type: Request
description: The Payer requests to assign or change the Payee.
payeeEmail:
  type: Text
---
name: Reserve Funds Requested
type: Request
description: A participant requests the Guarantor to reserve (hold) a specific amount.
amount:
  type: Integer
---
name: Reservation Release Requested
type: Request
description: A participant requests the Guarantor to release previously held funds.
amount:
  type: Integer
---
name: Capture Funds Requested
type: Request
description: A participant (usually the Payee) requests the final transfer of funds.
amount:
  type: Integer
---
name: Reserve Funds and Capture Immediately Requested
type: Request
description: Equivalent of Reserve Funds Requested + Capture Funds Requested
amount:
  type: Integer
---
name: Issue Child PayNote Requested
type: Request
description: |
  The Payer requests to issue a new PayNote.
  The requested PayNote must have amount/total specified and in the same currency as this PayNote.
  If approved by Guarator, amount/total of this PayNote will be deducted by this value.
  If child PayNote is later cancelled, or captured value is smaller than the total, the funds will be added back to amount/total.
childPayNote:
  description: Complete PayNote
---
name: PayNote Cancellation Requested
type: Request
description: |
  The Payer requests to cancel PayNote that is Approved but not yet 
  Reserved or Captured.
childPayNote:
  description: Complete PayNote

6. Use Cases & Complete Examples

The true power of the PayNote lies in its flexibility. It can model everything from a simple, one-off bank transfer to a complex, AI-managed budget. The following examples demonstrate how different configurations of the base PayNote type can achieve vastly different outcomes.

Example 1: Simple, Self-Executing Bank Transfer

Scenario: This is a standard, direct payment. Alice wants to send Bob $250.00, and the transfer should happen automatically as soon as the PayNote is created.

Implementation: This "fire-and-forget" payment is achieved with a bootstrap workflow that, upon initiation, immediately triggers a Reserve Funds and Capture Immediately Requested event.

name: Payment for Invoice Q3-SERVICES
type: PayNote

# --- Instance Data ---
currency: USD
amount:
  total: 25000 # $250.00

payNoteInitialStateDescription:
  summary: |
    This is a direct payment of **$250.00 USD** from Alice to Bob, securely processed by Citi Bank. The transfer will be executed automatically once this payment note is created.
  details: |
    This document authorizes a single, immediate transfer of funds.

    #### Participants
    * **Payer**: Alice (the sender)
    * **Payee**: Bob (the recipient)
    * **Guarantor**: Citi Bank (the financial institution handling the transfer)

    #### Operations
    There are no actions for any participant to take. This payment is fully automated.

    #### Scenarios
    * **Successful Transfer:** Upon creation, Citi Bank will automatically reserve and transfer the full $250.00 to Bob. No further steps are needed. A confirmation (`Funds Captured`) will be recorded here once complete.
    * **Failed Transfer:** If the transfer cannot be completed for any reason (e.g., insufficient funds), Citi Bank will record the failure here (`Reservation Declined` or `Capture Failed`), providing a clear and verifiable reason.

# --- Participants & Logic ---
contracts:
  bootstrap:
    type: Sequential Workflow
    event:
      type: Document Processing Initiated # Triggers on creation
    steps:
      - name: RequestImmediatePayment
        type: Trigger Event
        event:
          type: Reserve Funds and Capture Immediately Requested
          # Amount is intentionally omitted to default to the PayNote's total.

  payerChannel:
    type: MyOS Timeline # Bound to Alice's account
  payeeChannel:
    type: MyOS Timeline # Bound to Bob's account
  guarantorChannel:
    type: MyOS Timeline # Bound to Citi Bank's account

Example 2: Conditional Escrow for Shipment

Scenario: A customer (Payer) is paying a merchant (Payee) €120.00 for goods that will be delivered by DHL. The payment should be held securely by the bank (Guarantor) and only released to the merchant after DHL confirms the package has been delivered.

Implementation: This creates a 4-party escrow. The bootstrap workflow only reserves the funds. A new custom operation, shipmentConfirmed, is added and restricted to the shipmentCompanyChannel. Only when DHL calls this operation will the PayNote then trigger the final Capture Funds Requested.

name: Escrow Payment for Shipment #SH-481516
type: PayNote

# --- Instance Data ---
currency: EUR
amount:
  total: 12000 # €120.00

payNoteInitialStateDescription:
  summary: |
    This is a protected payment of **€120.00 EUR**. The funds are held securely by your bank and will only be released to the Merchant after **DHL confirms successful delivery**.
  details: |
    This PayNote acts as a secure escrow to protect the Payer. The payment is guaranteed, but the final transfer is conditional on a confirmation from the shipping company.

    #### Participants
    * **Payer**: The Customer (sender of funds)
    * **Payee**: The Merchant (recipient of funds)
    * **Guarantor**: The Bank (holds the funds in escrow)
    * **Shipment Company**: DHL (provides delivery confirmation)

    #### Operations
    * **`shipmentConfirmed`** (Callable by: **Shipment Company - DHL**)
        * This action is performed by DHL to certify that the delivery is complete. This is the trigger that releases the payment to the Merchant.

    #### Scenarios
    1.  **Payment and Delivery:**
        * The Payer initiates the payment, and the Bank immediately reserves (holds) the €120.00.
        * DHL delivers the package to the Payer.
        * DHL then calls the `shipmentConfirmed` operation on this document.
        * This automatically authorizes the Bank to transfer the €120.00 to the Merchant. The process is complete.
    2.  **Shipment Issue:**
        * If the shipment is never confirmed by DHL, the funds remain reserved. The Payer can then initiate a cancellation to have the funds released back to their account.

# --- Participants & Logic ---
contracts:
  bootstrap:
    type: Sequential Workflow
    event: { type: Document Processing Initiated }
    steps:
      - name: RequestReservation
        type: Trigger Event
        event:
          type: Reserve Funds Requested
          amount: ${document('/amount/total')}
  
  shipmentConfirmed:
    type: Operation
    description: Must be called by the Shipment Company to confirm delivery and trigger payment capture.
    channel: shipmentCompanyChannel # Only DHL can call this.

  shipmentConfirmedImpl:
    type: Sequential Workflow Operation
    operation: shipmentConfirmed
    steps:
      - name: RequestFinalCapture
        type: Trigger Event
        event:
          type: Capture Funds Requested
          amount: ${document('/amount/total')}

  # Participants
  payerChannel:
    type: MyOS Timeline # Bound to Customer's account
  payeeChannel:
    type: MyOS Timeline # Bound to Merchant's account
  guarantorChannel:
    type: MyOS Timeline # Bound to the Bank's account
  shipmentCompanyChannel:
    type: MyOS Timeline # Bound to DHL's account

Example 3: AI Agent Issuing Child PayNotes

Scenario: Alice wants to give her AI Shopping Agent a pre-approved budget of $1,000.00 to make multiple purchases on her behalf. The agent should be able to create smaller, independent payments for different vendors against this master budget.

Implementation: Alice creates a master PayNote and reserves the full amount. The document includes an issueChildPayNote operation that only she (or her agent, acting on her behalf) can call. This operation allows the agent to request the issuance of new, self-contained Child PayNotes.

name: AI Shopping Agent Managed Account
type: PayNote

# --- Instance Data ---
currency: USD
amount:
  total: 100000 # $1,000.00

payNoteInitialStateDescription:
  summary: |
    This document establishes a secure, pre-approved budget of **$1,000.00 USD** for an authorized AI Agent. The agent has been granted the ability to create and execute smaller, individual payments ("Child PayNotes") against this total budget.
  details: |
    This PayNote functions as a master account with a fixed, reserved limit. It does not make payments directly but authorizes the creation of smaller, linked payments.

    #### Participants
    * **Payer**: Alice (the owner of the funds)
    * **Guarantor**: Alice's Bank (the institution managing the funds)

    #### Operations
    * **`issueChildPayNote`** (Callable by: **Payer - Alice / Her Agent**)
        * This operation allows an authorized agent, acting on Alice's behalf, to request the issuance of a new, independent Child PayNote that draws funds from this master budget. The request must include the full details of the child payment, including its amount and payee.

    #### Scenarios
    1.  **Budget Setup:**
        * Alice creates this document, and her Bank immediately reserves the full $1,000.00. This action secures the total budget.
    2.  **Agent Initiates a Payment:**
        * The agent calls the `issueChildPayNote` operation.
        * The Bank validates that the requested amount is within the remaining budget.
        * If valid, the Bank creates the new Child PayNote and records its issuance here. The child payment then runs its own lifecycle (e.g., transferring funds to a vendor).
        * The available budget on this master document is automatically reduced.
    3.  **Budget Exceeded:**
        * If the agent attempts to issue a child payment that exceeds the available budget, the Bank will reject the request. The total spending can never exceed the initial $1,000.00.

# --- Participants & Logic ---
contracts:
  bootstrap:
    type: Sequential Workflow
    event: { type: Document Processing Initiated }
    steps:
      - name: ReserveFullBudget
        type: Trigger Event
        event:
          type: Reserve Funds Requested
          amount: ${document('/amount/total')}

  issueChildPayNote:
    type: Operation
    description: Allows the Payer (or their agent) to issue a new Child PayNote against the reserved funds.
    channel: payerChannel # Only Alice or her agent can call this.
    request:
      type: PayNote # Expects a complete PayNote document as input.

  issueChildPayNoteImpl:
    type: Sequential Workflow Operation
    operation: issueChildPayNote
    steps:
      - name: RequestChildIssuance
        type: Trigger Event
        event:
          type: Issue Child PayNote Requested
          childPayNote: ${event.request}

  # Participants
  payerChannel:
    type: MyOS Timeline # Bound to Alice's account
  guarantorChannel:
    type: MyOS Timeline # Bound to the Bank's account
  # payeeChannel is left unbound at this master level.

1. Introduction & Overview​

2. Core Concepts​

The Three Participants​

The Event-Driven Lifecycle​

Child PayNotes: Subdividing Value​

3. The Base PayNote Definition​

4. PayNote Events (The Guarantor's Vocabulary)​

Lifecycle Events​

Reservation Events​

Capture Events​

Settlement & Child PayNote Events​

5. PayNote Requests (The Participant's Vocabulary)​

6. Use Cases & Complete Examples​

Example 1: Simple, Self-Executing Bank Transfer​

Example 2: Conditional Escrow for Shipment​

Example 3: AI Agent Issuing Child PayNotes​