1. Scope and Interpretation

1.1 Purpose

This document provides non-normative reference material for yona:ruleset:v1.0, including:

• reference message sequences
• decoded payload examples
• DID document examples
• publication examples
• implementation guidance

These materials are intended to make the ruleset and companion documents easier to read and implement. They do not change the meaning of the ruleset, the Base Interoperability Profile (BIP), or the YONA Conformance Test Suite.

1.2 Relationship to companion documents

If any example in this document appears to conflict with a normative rule, the normative rule controls.

1.3 Rendered pages and downloadable artifacts

This page is provided for reading and reference.

The examples shown in this document are illustrative. They are not fixture bytes and are not authoritative for hashing. For request_jws_sha256, exact-byte authority remains with the corresponding YONA Conformance Test Suite artifacts and any raw fixture files that the suite designates as authoritative.

2. Reference Message Sequences

This section does not add requirements.

2.1 Pull-payment (ACCEPT)

1. The beneficiary side presents an intent_locator.
2. The originator VASP resolves intent_locator.beneficiary_vasp_did via did:web.
3. The originator VASP sends signed yona.retrieve_intent to YonaPaymentIntentService.
4. The beneficiary VASP returns signed yona.payment_intent.
5. The originator VASP verifies yona.payment_intent and obtains user confirmation.
6. The originator VASP sends signed yona.authorization_request in pull-payment form to YonaAuthorizationService.
7. The beneficiary VASP returns signed yona.authorization_response with decision = ACCEPT.
8. The originator VASP proceeds to out-of-scope post-ACCEPT steps.

2.2 Pull-payment (REJECT)

Same as Section 2.1 through Step 6, then:

1. The beneficiary VASP returns signed yona.authorization_response with decision = REJECT.
2. The originator VASP MUST NOT proceed to post-ACCEPT steps for that intent.

2.3 Push-payment (ACCEPT)

1. The originator obtains a beneficiary_handle in normative form.
2. The originator VASP resolves the beneficiary DID via did:web.
3. The originator VASP obtains user confirmation on the proposed payment_terms and intended_asset_type.
4. The originator VASP sends signed yona.authorization_request in push-payment form to YonaAuthorizationService.
5. The beneficiary VASP returns signed yona.authorization_response with decision = ACCEPT.
6. The originator VASP proceeds to out-of-scope post-ACCEPT steps.

2.4 Push-payment (REJECT)

Same as Section 2.3 through Step 4, then:

1. The beneficiary VASP returns signed yona.authorization_response with decision = REJECT.
2. The originator VASP MUST NOT proceed to post-ACCEPT steps for that intent.

2.5 Authorization NO_RESPONSE

This sequence illustrates the timeout outcome for authorization.

1. The originator VASP sends signed yona.authorization_request to YonaAuthorizationService.
2. No valid, verified terminal yona.authorization_response is obtained within 60 seconds.
3. The originator VASP concludes NO_RESPONSE.
4. Under yona:ruleset:v1.0, NO_RESPONSE is treated as REJECT.
5. The originator VASP MUST NOT proceed to post-ACCEPT steps.

2.6 Retrieval failure

This sequence illustrates pull-payment retrieval failure.

1. The originator VASP resolves intent_locator.beneficiary_vasp_did.
2. The originator VASP sends signed yona.retrieve_intent to YonaPaymentIntentService.
3. No valid, verified yona.payment_intent is obtained.
4. The outcome is retrieval failure, not ACCEPT, REJECT, or authorization NO_RESPONSE.
5. The originator VASP MUST NOT proceed to authorization using locator-only data.

3. Canonical Decoded Payload Examples

The examples below show decoded payloads. They are illustrative only. They are not fixture bytes and are not authoritative for hashing.

3.1 Pull-payment yona.retrieve_intent

{
  "iss": "did:web:originator.example",
  "aud": "did:web:beneficiary.example",
  "iat": 1760001000,
  "exp": 1760001060,
  "jti": "jti_pull_retrieve_intent_0001",
  "message_type": "yona.retrieve_intent",
  "ruleset_id": "yona:ruleset:v1.0",
  "intent_locator": {
    "type": "yona.intent_locator",
    "beneficiary_vasp_did": "did:web:beneficiary.example",
    "beneficiary_intent_id": "beneficiary_intent_0001"
  }
}

3.2 Pull-payment yona.payment_intent

{
  "iss": "did:web:beneficiary.example",
  "aud": "did:web:originator.example",
  "iat": 1760001001,
  "exp": 1760001061,
  "jti": "jti_pull_payment_intent_0001",
  "message_type": "yona.payment_intent",
  "ruleset_id": "yona:ruleset:v1.0",
  "intent_locator": {
    "type": "yona.intent_locator",
    "beneficiary_vasp_did": "did:web:beneficiary.example",
    "beneficiary_intent_id": "beneficiary_intent_0001"
  },
  "payment_terms": {
    "amount": "1250",
    "amount_units": "minor",
    "currency": "USD"
  },
  "acceptable_asset_types": [
    "eip155:1/erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
  ]
}

3.3 Pull-payment yona.authorization_request

{
  "iss": "did:web:originator.example",
  "aud": "did:web:beneficiary.example",
  "iat": 1760001002,
  "exp": 1760001062,
  "jti": "jti_pull_authorization_request_0001",
  "message_type": "yona.authorization_request",
  "ruleset_id": "yona:ruleset:v1.0",
  "intent_id": "originator_pull_intent_0001",
  "embedded_payment_intent": "<exact JWS Compact Serialization of a previously returned yona.payment_intent>"
}

3.4 Push-payment yona.authorization_request

{
  "iss": "did:web:originator.example",
  "aud": "did:web:beneficiary.example",
  "iat": 1760002000,
  "exp": 1760002060,
  "jti": "jti_push_authorization_request_0001",
  "message_type": "yona.authorization_request",
  "ruleset_id": "yona:ruleset:v1.0",
  "intent_id": "originator_push_intent_0001",
  "beneficiary_handle": "did=did:web:beneficiary.example;alias=alias_0001",
  "payment_terms": {
    "amount": "1250",
    "amount_units": "minor",
    "currency": "USD"
  },
  "intended_asset_type": "eip155:1/erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
}

3.5 yona.authorization_response (ACCEPT)

{
  "iss": "did:web:beneficiary.example",
  "aud": "did:web:originator.example",
  "iat": 1760002001,
  "exp": 1760002061,
  "jti": "jti_authorization_response_0001",
  "message_type": "yona.authorization_response",
  "ruleset_id": "yona:ruleset:v1.0",
  "intent_id": "originator_push_intent_0001",
  "decision": "ACCEPT",
  "request_jws_sha256": "<base64url(SHA-256(exact authorization request compact JWS bytes))>"
}

3.6 yona.authorization_response (REJECT)

{
  "iss": "did:web:beneficiary.example",
  "aud": "did:web:originator.example",
  "iat": 1760002001,
  "exp": 1760002061,
  "jti": "jti_authorization_response_0002",
  "message_type": "yona.authorization_response",
  "ruleset_id": "yona:ruleset:v1.0",
  "intent_id": "originator_push_intent_0001",
  "decision": "REJECT",
  "request_jws_sha256": "<base64url(SHA-256(exact authorization request compact JWS bytes))>"
}

4. DID Document and Capability Examples

4.1 Minimum full-BIP beneficiary DID document

This example shows the minimum beneficiary-side DID service entries for a deployment claiming full YONA conformance under yona:ruleset:v1.0.

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/suites/jws-2020/v1"
  ],
  "id": "did:web:beneficiary.example",
  "verificationMethod": [
    {
      "id": "did:web:beneficiary.example#sig-1",
      "type": "JsonWebKey2020",
      "controller": "did:web:beneficiary.example",
      "publicKeyJwk": {
        "kty": "OKP",
        "crv": "Ed25519",
        "x": "2Qt...REPLACE_WITH_REAL_BASE64URL..."
      }
    }
  ],
  "assertionMethod": [
    "did:web:beneficiary.example#sig-1"
  ],
  "service": [
    {
      "id": "did:web:beneficiary.example#yona-payment-intent",
      "type": "YonaPaymentIntentService",
      "serviceEndpoint": "https://beneficiary.example/yona/payment-intent"
    },
    {
      "id": "did:web:beneficiary.example#yona-authorization",
      "type": "YonaAuthorizationService",
      "serviceEndpoint": "https://beneficiary.example/yona/authorization"
    }
  ]
}

4.2 Push-payment pilot DID document (non-conformance claim)

This example shows a push-payment pilot deployment that does not claim full YONA conformance.

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/suites/jws-2020/v1"
  ],
  "id": "did:web:beneficiary.example",
  "verificationMethod": [
    {
      "id": "did:web:beneficiary.example#sig-1",
      "type": "JsonWebKey2020",
      "controller": "did:web:beneficiary.example",
      "publicKeyJwk": {
        "kty": "OKP",
        "crv": "Ed25519",
        "x": "2Qt...REPLACE_WITH_REAL_BASE64URL..."
      }
    }
  ],
  "assertionMethod": [
    "did:web:beneficiary.example#sig-1"
  ],
  "service": [
    {
      "id": "did:web:beneficiary.example#yona-authorization",
      "type": "YonaAuthorizationService",
      "serviceEndpoint": "https://beneficiary.example/yona/authorization"
    }
  ]
}

4.3 DID document with optional Travel Rule discovery pointer

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/suites/jws-2020/v1"
  ],
  "id": "did:web:beneficiary.example",
  "verificationMethod": [
    {
      "id": "did:web:beneficiary.example#sig-1",
      "type": "JsonWebKey2020",
      "controller": "did:web:beneficiary.example",
      "publicKeyJwk": {
        "kty": "OKP",
        "crv": "Ed25519",
        "x": "2Qt...REPLACE_WITH_REAL_BASE64URL..."
      }
    }
  ],
  "assertionMethod": [
    "did:web:beneficiary.example#sig-1"
  ],
  "service": [
    {
      "id": "did:web:beneficiary.example#yona-payment-intent",
      "type": "YonaPaymentIntentService",
      "serviceEndpoint": "https://beneficiary.example/yona/payment-intent"
    },
    {
      "id": "did:web:beneficiary.example#yona-authorization",
      "type": "YonaAuthorizationService",
      "serviceEndpoint": "https://beneficiary.example/yona/authorization"
    },
    {
      "id": "did:web:beneficiary.example#travel-rule",
      "type": "YonaTravelRuleService",
      "serviceEndpoint": "https://beneficiary.example/.well-known/yona/capabilities/travel-rule"
    }
  ]
}

4.4 DID document with optional assurance endpoint

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/suites/jws-2020/v1"
  ],
  "id": "did:web:beneficiary.example",
  "verificationMethod": [
    {
      "id": "did:web:beneficiary.example#sig-1",
      "type": "JsonWebKey2020",
      "controller": "did:web:beneficiary.example",
      "publicKeyJwk": {
        "kty": "OKP",
        "crv": "Ed25519",
        "x": "2Qt...REPLACE_WITH_REAL_BASE64URL..."
      }
    }
  ],
  "assertionMethod": [
    "did:web:beneficiary.example#sig-1"
  ],
  "service": [
    {
      "id": "did:web:beneficiary.example#yona-payment-intent",
      "type": "YonaPaymentIntentService",
      "serviceEndpoint": "https://beneficiary.example/yona/payment-intent"
    },
    {
      "id": "did:web:beneficiary.example#yona-authorization",
      "type": "YonaAuthorizationService",
      "serviceEndpoint": "https://beneficiary.example/yona/authorization"
    },
    {
      "id": "did:web:beneficiary.example#assurance",
      "type": "YonaAssuranceService",
      "serviceEndpoint": "https://beneficiary.example/.well-known/yona/assurance"
    }
  ]
}

4.5 Capability document examples (illustrative only)

Under the BIP, if YonaTravelRuleService is published, its serviceEndpoint points to a capability document.

That capability document is out-of-band service metadata only. It does not change YONA authorization semantics.

The BIP defines the required minimum fields for YonaTravelRuleService capability discovery. The following JSON examples are illustrative only and show possible capability documents that include those required fields.

4.5.1 Travel Rule capability document example — TRP

{
  "service_type": "YonaTravelRuleService",
  "protocol": "trp",
  "supported_versions": [
    "3"
  ],
  "endpoints": [
    {
      "uri": "https://beneficiary.example/travel-rule/trp",
      "transport": "https"
    }
  ],
  "auth": [
    "mTLS"
  ],
  "provider_identity": "Example Beneficiary VASP",
  "documentation_uri": "https://beneficiary.example/docs/trp"
}

4.5.2 Travel Rule capability document example — TRISA

{
  "service_type": "YonaTravelRuleService",
  "protocol": "trisa",
  "supported_versions": [
    "v1.7.0"
  ],
  "endpoints": [
    {
      "uri": "trisa://beneficiary.example:443",
      "transport": "mTLS"
    }
  ],
  "auth": [
    "mTLS",
    "X.509"
  ],
  "provider_identity": "Example Beneficiary VASP",
  "documentation_uri": "https://beneficiary.example/docs/trisa"
}

4.6 Key rotation example (pattern)

A typical key-rotation pattern under did:web is:

1. Publish the new key (for example, #sig-2) in the DID document.
2. Keep the old key (for example, #sig-1) during an overlap window.
3. Start signing new messages with kid = ...#sig-2.
4. Remove the old key after the cache horizon or rollout window.

This is an operational pattern only. The ruleset does not define a mandatory key-rotation schedule.

5. Example Publication Patterns

5.1 Publishing the DID used for YONA interactions

An implementer may publish the VASP DID used for YONA interactions on its website, in developer documentation, or in an interoperability profile.

Example:

YONA DID: did:web:beneficiary.example

5.2 Public declaration of supported rulesets and status

An implementer may publish a public declaration under its own control describing supported ruleset_id values, interaction scope, and deployment status.

Example:

{
  "did": "did:web:beneficiary.example",
  "supported_ruleset_ids": [
    "yona:ruleset:v1.0"
  ],
  "supported_interaction_scope": "push",
  "conformance_status": "Push-payment pilot support under yona:ruleset:v1.0 (non-conformance claim)"
}

This is only a convenience signal. DID discovery remains authoritative under BIP.

5.3 Suggested labels

Suggested public labels include:

• No conformance claim
• Push-payment pilot support under yona:ruleset:v1.0 (non-conformance claim)
• YONA-conformant implementation of yona:ruleset:v1.0

Use pilot labels only when those statements are accurate and do not imply full YONA conformance.

6. Implementation Guidance

6.1 Common drift points

1. Hashing the wrong bytes

   request_jws_sha256 hashes the exact compact JWS ASCII bytes, not decoded JSON.

2. Treating retrieval failures as authorization semantics

   Retrieval failure blocks the pull-payment flow but is not ACCEPT, REJECT, or authorization NO_RESPONSE.

3. Conflating bindable invalid requests with unbindable bodies

   A request can be invalid yet bindable, in which case the beneficiary returns a signed REJECT.

   A malformed or unparseable body may be unbindable, in which case the beneficiary MUST NOT return a YONA JWS response message.

4. Handle-form drift

   The normative beneficiary_handle form for Ruleset 1.0 is:

   did=<beneficiary_vasp_did>;alias=<opaque_alias>

   Changing field names, separators, delimiters, or constraints changes validation behavior and can break interoperability.

5. Field-name drift across drafts or internal notes

   For the active Ruleset 1.0 release, the pull-payment field is acceptable_asset_types and the push-payment field is intended_asset_type.

   Using older or alternate names such as acceptable_assets or intended_asset changes validation behavior and can break interoperability.

6. Service-type drift

   Under the ruleset and BIP, the required DID service.type values are:

   YonaPaymentIntentService

   YonaAuthorizationService

   Omitting the Service suffix changes endpoint discovery behavior and can break interoperability.

7. Treating optional DID services as normative

   Optional DID services such as YonaTravelRuleService, YonaSettlementService, or YonaAssuranceService are out of band. Their presence or absence does not change YONA authorization semantics or YONA conformance.

8. Modeling push authorization input as if it were a retrieved pull-payment intent

   Push-payment authorization uses beneficiary_handle, payment_terms, and intended_asset_type directly. Pull-payment authorization depends on a retrieved beneficiary-authored yona.payment_intent. These are not the same protocol artifact.

6.2 Pull-payment implementation reminder

For pull-payment, intent_locator is only a reference used to retrieve the authoritative signed yona.payment_intent.

The originator VASP should not treat the unsigned locator as the authoritative payment terms.

6.3 Push-payment implementation reminder

For push-payment, the beneficiary_handle is an opaque beneficiary-side reference. The originator VASP should not infer settlement instructions, destination coordinates, rails, or pricing semantics from it.

No yona.payment_intent is retrieved for push-payment.

6.4 Optional service reminder

Optional DID services such as YonaTravelRuleService, YonaSettlementService, and YonaAssuranceService are discovery pointers only. They do not create new YONA message types and do not change YONA authorization semantics.

If a capability document is used for YonaTravelRuleService or YonaSettlementService, the BIP requires it to be treated as out-of-band service metadata only.