1. Scope and Interpretation

1.1 Purpose

This document defines the Base Interoperability Profile (BIP) for implementations claiming conformance to yona:ruleset:v1.0.

BIP exists so independently built implementations can interoperate without bespoke per-counterparty authorization integrations.

For yona:ruleset:v1.0, BIP defines a common baseline for:

• counterparty discovery
• service endpoint discovery
• HTTPS transport
• JOSE message carriage
• endpoint-specific request and response behavior

1.2 Relationship to companion documents

This document is the interoperable baseline for yona:ruleset:v1.0. It defines how independent implementations discover counterparties for YONA interactions, publish and select required service endpoints, carry YONA messages, and behave at those endpoints.

This companion does not create new YONA message semantics. YONA Ruleset 1.0 remains authoritative for YONA semantics and message-level requirements.

1.3 What this document covers

This document defines the full BIP baseline for yona:ruleset:v1.0.

It specifies:

• did:web counterparty discovery for YONA interactions;
• discovery and selection of required YONA DID service entries;
• HTTPS transport for YONA messages;
• application/jose message carriage using JWS Compact Serialization; and
• endpoint-specific behavior for BIP requests and responses.

This document also defines optional machine-readable discovery for post-ACCEPT out-of-band services, including optional DID service entries such as YonaTravelRuleService and YonaAssuranceService.

Where this BIP requires an advertised optional service entry to point to a capability document or other required document, this document defines the minimum requirements for that document.

That optional discovery does not change YONA authorization semantics and does not define Travel Rule payloads, settlement payloads, or settlement execution.

Illustrative examples appear in Reference Messages and DID Examples. Those examples are non-normative.

1.4 What this document does not cover

This document does not define systems outside the YONA authorization layer.

This BIP does not define:

• Travel Rule payloads;
• Travel Rule transport payload semantics;
• settlement-instruction payload semantics;
• settlement execution;
• runtime relays, routing, or directory services;
• local compliance policy; or
• out-of-band trust, licensing, or commercial arrangements.

2. BIP Baseline

2.1 Baseline under yona:ruleset:v1.0

This subsection states the minimum interoperable baseline required for YONA conformance under yona:ruleset:v1.0.

To claim YONA conformance, an implementation MUST support:

• did:web counterparty discovery;
• DID-document discovery of required YONA service endpoints;
• HTTPS POST;
• Content-Type: application/jose;
• Accept: application/jose;
• JWS Compact Serialization request and response bodies; and
• the endpoint-specific behavior defined in this BIP and in YONA Ruleset 1.0.

Implementations MAY support additional transports or discovery arrangements for YONA by mutual agreement, but those arrangements are outside YONA conformance and MUST preserve the same YONA message bytes and semantics.

2.2 Roles under BIP

BIP covers both sides of the interoperable YONA interaction model.

The roles under BIP are:

For a YONA conformance claim under yona:ruleset:v1.0, the implementation and test evidence MUST cover both roles.

3. DID Discovery and Service Exposure

3.1 DID method under BIP

This subsection defines the DID method required under BIP.

For conformance to yona:ruleset:v1.0, implementations MUST support did:web resolution for YONA interactions.

BIP does not require support for any other DID method.

3.2 Required beneficiary-side service entries for full YONA conformance

This subsection defines which DID service entries a beneficiary-side implementation must publish for full YONA conformance.

To claim full YONA conformance as a beneficiary-side implementation under yona:ruleset:v1.0, a VASP MUST publish the following DID service entries:

• type: "YonaPaymentIntentService"
• type: "YonaAuthorizationService"

A beneficiary-side implementation claiming full YONA conformance under yona:ruleset:v1.0 MUST publish both service types, even if a particular deployment operationally uses only one flow.

3.3 Endpoint selection by flow

This subsection defines which service type each Ruleset 1.0 flow uses.

Under BIP:

• pull-payment intent retrieval MUST use type: "YonaPaymentIntentService"
• authorization, for both pull-payment and push-payment, MUST use type: "YonaAuthorizationService"

3.4 Verification keys and kid resolution

This subsection defines the DID-published verification material needed for signed YONA messages.

A DID document used for YONA interactions MUST publish the verification material needed for counterparties to resolve JWS kid values and verify signatures.

The sender's kid MUST resolve under the sender DID used in iss, consistent with the ruleset.

3.5 Discovery failure handling

This subsection defines what happens when DID resolution or service discovery fails.

If the required DID document cannot be resolved, or if the required service entry is missing, invalid, or unusable, the initiating VASP MUST NOT send the YONA request.

Failure consequences remain endpoint-specific:

• inability to use YonaPaymentIntentService is a retrieval failure
• inability to use YonaAuthorizationService means no valid terminal authorization response was obtained; authorization outcome handling remains governed by the ruleset

3.6 Optional discovery pointers and capability discovery

This subsection defines optional DID service entries that remain outside YONA authorization semantics.

A DID document MAY advertise optional service entries such as:

• type: "YonaTravelRuleService"
• type: "YonaAssuranceService"

These optional services are out of band.

The presence, absence, retrieval, or use of these optional service entries or any information discovered through them MUST NOT affect:

• YONA message validity
• authorization evaluation
• request/response binding
• terminal outcomes

If a VASP advertises YonaTravelRuleService, the capability-document requirements for BIP-defined discovery are specified in Section 3.6.1.

These optional service entries do not define Travel Rule payload semantics, Travel Rule transport payload semantics, or local policy outcomes.

3.6.1 YonaTravelRuleService capability documents

This subsection defines the discovery shape for optional post-ACCEPT Travel Rule capability discovery.

If a DID document advertises YonaTravelRuleService, its serviceEndpoint MUST identify a machine-readable capability document.

The serviceEndpoint for YonaTravelRuleService MUST NOT identify a directly usable out-of-band service endpoint.

That capability document MUST be retrievable over HTTPS.

A capability document under this subsection MUST be treated as out-of-band service metadata only. It does not change YONA authorization semantics by itself.

A YonaTravelRuleService capability document MUST identify the following required minimum fields:

• service_type
• protocol
• supported_versions
• endpoints
• auth

These are the required minimum fields for BIP-defined YonaTravelRuleService capability discovery under yona:ruleset:v1.0.

A VASP MAY include additional fields for supplementary implementation-specific, provider-specific, or protocol-specific information it deems necessary for interoperability.

Illustrative examples of YonaTravelRuleService capability documents that include these required minimum fields appear in Section 4.5 of Reference Messages and DID Examples.

A capability document MUST NOT be treated as changing:

• YONA message validity
• authorization evaluation
• request/response binding
• terminal outcomes

A VASP MAY use such capability information under local policy to decide whether and how to attempt post-ACCEPT Travel Rule exchange outside YONA.

3.6.2 YonaAssuranceService

This subsection defines the optional assurance discovery pointer.

YonaAssuranceService is an optional out-of-band discovery pointer for assurance material that a VASP may evaluate under its own local counterparty-risk policy.

Such assurance material MAY include:

• conformance claims
• conformance reports
• certificates
• provider attestations
• regulatory, licensing, registration, or jurisdictional references
• equivalent assurance artifacts

A VASP MAY use such assurance material under local policy to support counterparty due diligence, establish a counterparty relationship, or decide whether to transact with that counterparty.

YonaAssuranceService is only an assurance discovery pointer. It does not determine whether a counterparty is trusted, licensed, regulated, eligible to receive Travel Rule data, or approved for settlement. It also does not define Travel Rule capability discovery or settlement capability discovery.

4. HTTP and JOSE Transport

4.1 Request transport

This subsection defines how YONA requests are carried over HTTP under BIP.

Under BIP, the client MUST send an HTTPS POST to the resolved serviceEndpoint.

For YONA requests:

• the HTTP request body MUST be the exact JWS Compact Serialization string for the applicable YONA message
• Content-Type MUST be application/jose
• the client MUST include Accept: application/jose

BIP defines no alternative JSON envelope, detached-signature profile, or multipart representation.

4.2 YONA response messages

This subsection defines what counts as a valid YONA response message under BIP.

A YONA response message under BIP is an HTTP 200 response with Content-Type: application/jose whose body is a valid JWS Compact Serialization for a defined YONA message type.

When a BIP endpoint returns a YONA message, it MUST do so in that form.

4.3 Channel security

This subsection prevents messages from being sent to or accepted from the wrong HTTPS endpoint.

HTTPS endpoints used under BIP MUST support TLS 1.2 or higher.

Implementations SHOULD support TLS 1.3.

Clients MUST validate the server certificate chain and the server identity for the intended endpoint.

Additional channel-security controls, such as mutual TLS (mTLS) or connection allowlists, are local policy. Such controls MAY restrict practical reachability, but they do not change YONA message validity, authorization semantics, or YONA conformance.

4.4 Message parsing and exact-byte evaluation

This subsection ensures that the same message is interpreted the same way across implementations.

Under BIP:

• requests and responses MUST be carried as JWS Compact Serialization
• messages MUST be evaluated exactly as received
• the decoded JWS payload MUST be valid UTF-8 JSON
• duplicate JSON object member names are invalid and MUST be rejected
• receivers MUST detect duplicate member names, either through parser support or by inspecting the raw message content
• timestamps MUST be integers, consistent with the ruleset

Implementations MUST NOT re-wrap YONA messages in another application-layer format while claiming YONA conformance.

5. Endpoint Behavior Under BIP

5.1 YonaPaymentIntentService

This subsection defines the pull-payment retrieval endpoint under BIP.

YonaPaymentIntentService is the beneficiary-side endpoint used for pull-payment intent retrieval.

Upon successful processing of yona.retrieve_intent, the server MUST return:

• HTTP 200
• Content-Type: application/jose
• body = JWS Compact Serialization of a yona.payment_intent

Ruleset 1.0 defines no signed retrieval decision message and no retrieval-specific REJECT message type.

YonaPaymentIntentService MUST NOT return yona.authorization_response.

If the server cannot, or will not, return a valid yona.payment_intent, it MUST NOT return a YONA response message.

Clients MUST treat any outcome other than a valid, verified yona.payment_intent as a payment intent retrieval failure and MUST NOT proceed to authorization for that pull-payment flow.

A retrieval failure is not an authorization outcome and MUST NOT be displayed or processed as ACCEPT, REJECT, or NO_RESPONSE.

5.2 YonaAuthorizationService

This subsection defines the terminal authorization endpoint under BIP.

YonaAuthorizationService is the beneficiary-side endpoint used for pull-payment and push-payment authorization.

For any received yona.authorization_request that the beneficiary VASP can process and can bind to a terminal response, including deterministic rejection, the server MUST return:

• HTTP 200
• Content-Type: application/jose
• body = JWS Compact Serialization of terminal yona.authorization_response (ACCEPT or REJECT)

If a received yona.authorization_request fails validation gating and the server can construct a structurally valid bound response, it MUST return a signed terminal REJECT and MUST NOT proceed to authorization evaluation.

If the server cannot construct a bound terminal response because required routing or binding inputs are missing or invalid, it MUST NOT return a YONA response message.

5.2.1 Minimum inputs to form a bound terminal response

This subsection states the minimum information the beneficiary VASP must have before it can produce a bound terminal response.

To construct a bound terminal yona.authorization_response, the server MUST be able to:

1. preserve the exact request JWS Compact Serialization as received
2. parse payload JSON to extract string values for iss, aud, intent_id, message_type, and ruleset_id
3. construct a structurally valid yona.authorization_response using:
   • iss = authorization_request.aud
   • aud = authorization_request.iss
   • intent_id = authorization_request.intent_id
   • decision = ACCEPT or REJECT
   • request_jws_sha256 = base64url(SHA-256(<exact request JWS Compact Serialization as received>))

These minimum inputs determine only whether a bound response can be formed. They do not imply the request is valid or authorized.

If the server cannot obtain these minimum inputs, it MUST NOT return a YONA response message.

5.3 Authorization no-response handling

This subsection defines the originator-side consequence of not obtaining a valid terminal authorization response.

For authorization requests, absence of a valid, verified terminal yona.authorization_response by the cutoff is NO_RESPONSE.

Under yona:ruleset:v1.0, NO_RESPONSE MUST be treated as REJECT.

Once the originator VASP has concluded NO_RESPONSE, any later yona.authorization_response for that attempt MUST be ignored and MUST NOT change the outcome.

5.4 Retrieval failure separation

This subsection preserves the ruleset boundary between pull-payment retrieval and terminal authorization.

BIP preserves the distinction between:

• retrieval failure for YonaPaymentIntentService
• authorization outcomes for YonaAuthorizationService

A retrieval failure MUST NOT be treated as ACCEPT, REJECT, or authorization NO_RESPONSE.

In pull-payment, the authoritative beneficiary-authored artifact is a retrieved yona.payment_intent.

In push-payment, authorization proceeds from beneficiary_handle, payment_terms, and required intended_asset_type carried in yona.authorization_request.

These are not the same protocol artifact and MUST NOT be modeled as if they were.

6. YONA Conformance Scope

6.1 Full YONA conformance under yona:ruleset:v1.0

This subsection defines what full YONA conformance means for Ruleset 1.0.

To claim full YONA conformance for yona:ruleset:v1.0, an implementation MUST support the full interaction model required by YONA Ruleset 1.0 and this profile, including:

• pull-payment discovery and retrieval via YonaPaymentIntentService
• authorization via YonaAuthorizationService for both pull-payment and push-payment flows
• DID discovery and key resolution under did:web
• BIP transport and endpoint behavior

6.2 Conformance evidence

This subsection defines the minimum conditions for making a YONA conformance claim under yona:ruleset:v1.0.

A YONA conformance claim for yona:ruleset:v1.0 MUST NOT be made unless the implementation:

• satisfies all applicable normative requirements in YONA Ruleset 1.0;
• satisfies all applicable normative requirements in this BIP; and
• passes all applicable normative test cases in the YONA Conformance Test Suite.

If the implementation advertises an optional BIP-defined DID service entry, the normative test cases in the YONA Conformance Test Suite that correspond to that service entry are applicable and MUST be passed for a YONA conformance claim. If this BIP requires that advertised service entry to point to a capability document or other required document, the corresponding normative test cases for that document are also applicable and MUST be passed.

The YONA Conformance Test Suite verifies conformance to YONA Ruleset 1.0 and this BIP. It adds no new protocol requirements beyond those documents.

If a conformance report is produced, it SHOULD state:

• the tested ruleset_id;
• any optional BIP-defined DID service entries advertised during testing; and
• any configuration inputs that materially affect validation, timeout handling, replay handling, caching, or repeated-request behavior.

6.3 Conformance statements, attestations, and credentials

Making a YONA conformance claim under yona:ruleset:v1.0 is optional. However, any implementation that claims YONA conformance MUST satisfy the requirements of this section and the applicable companion materials.

Conformance claims do not affect YONA message validity, authorization semantics, request/response binding, terminal outcomes, endpoint behavior, or YONA conformance itself.

No issuer has exclusive authority to determine, declare, issue, publish, or display a YONA conformance claim under yona:ruleset:v1.0.

A VASP MAY make a self-asserted YONA conformance claim for its own implementation after determining that the implementation satisfies all applicable normative requirements of YONA Ruleset 1.0 and this BIP document and has passed the applicable YONA Conformance Test Suite.

Third parties MAY assess an implementation and MAY issue a conformance statement, attestation, report, or credential under their own governance and review process.

Any claim of technical conformance MUST be based on the applicable normative requirements of YONA Ruleset 1.0 and this BIP document and on passing the applicable YONA Conformance Test Suite.

Such claims MAY be expressed in any format chosen by the claimant or assessor, including a website statement, signed report, PDF certificate, registry entry, or Verifiable Credential (VC) whose subject is the VASP DID or other implementation identifier.

This BIP does not require, define, or prefer any specific issuer, publication venue, display method, registry, trust framework, or credential format for conformance claims.

The presence, absence, or form of any such claim or credential MUST NOT be treated as changing the technical meaning of YONA conformance under yona:ruleset:v1.0.

7. Publication and Later Releases

7.1 Open implementation

This subsection states that BIP is open to read and implement.

BIP is an open interoperability baseline.

No approval, membership, contract, or commercial relationship with YONA LLC is required to read, implement, test, or evaluate this profile.

If a future YONA successor body is formed, membership in that entity likewise is not required to read, implement, test, or evaluate this profile.

7.2 Publication and immutability

This subsection explains how this companion relates to later stewardship or later releases.

This BIP is companion material for yona:ruleset:v1.0 and is currently published by YONA LLC.

If YONA LLC later transfers stewardship of future YONA releases to a successor body, that transition MUST NOT retroactively alter the meaning of this document for yona:ruleset:v1.0.

If a materially changed BIP baseline is approved for a future YONA release, that change MUST be published under the corresponding future release and MUST NOT retroactively alter the meaning of this document for yona:ruleset:v1.0.