1. Scope and Interpretation

1.1 Purpose

This document defines the Base Interoperability Profile 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 the ruleset

This companion does not create new YONA message semantics.

YONA Ruleset 1.0 remains authoritative for:

• message validity
• required fields
• terminal authorization semantics
• timeout and NO_RESPONSE handling
• request/response binding
• replay and repeated-request behavior
• out-of-scope boundaries

This document defines the interoperable baseline an implementation MUST implement in order to make a BIP conformance claim for yona:ruleset:v1.0.

1.3 What this document covers

This document covers the reusable interoperability baseline for how counterparties find each other, where they send YONA messages, how those messages are carried, and how BIP endpoints behave.

This document also defines optional machine-readable discovery for post-ACCEPT out-of-band service capabilities. That capability discovery does not change YONA authorization semantics and does not define Travel Rule payloads, settlement payloads, or settlement execution.

1.4 What this document does not cover

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

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
• out-of-band trust, licensing, or commercial arrangements

2. BIP Baseline

2.1 Baseline under yona:ruleset:v1.0

This subsection states the minimum baseline required for BIP conformance under Ruleset 1.0.

To claim BIP conformance for yona:ruleset:v1.0, 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
• endpoint-specific response behavior defined in this profile and the ruleset

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

2.2 Roles under BIP

This subsection identifies the roles that may be tested or claimed under BIP.

BIP applies to one or both of the following roles:

Originator VASP client

• resolves counterparty DID documents
• locates required service endpoints
• sends yona.retrieve_intent and/or yona.authorization_request
• verifies yona.payment_intent and yona.authorization_response

Beneficiary VASP server

• publishes required DID service entries
• receives YONA requests
• returns yona.payment_intent and/or terminal yona.authorization_response according to the ruleset

If a conformance report is produced, it SHOULD state:

• which role or roles were tested; and
• which interaction scope was tested (pull, push, or both).

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 BIP conformance

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

To claim full BIP 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 BIP conformance for yona:ruleset:v1.0 MUST publish both service types, even if a particular deployment operationally uses only one flow.

A push-payment-only pilot or other accurately described subset deployment that does not claim full BIP conformance MAY publish only:

• type: "YonaAuthorizationService"

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: "YonaSettlementService"
• 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
• BIP conformance

These optional service entries do not define Travel Rule payload semantics, settlement-instruction payload semantics, settlement execution, or local policy outcomes.

3.6.1 YonaTravelRuleService and YonaSettlementService capability documents

This subsection defines an optional machine-readable discovery pattern for post-ACCEPT out-of-band service capabilities.

If a DID document advertises YonaTravelRuleService or YonaSettlementService, its serviceEndpoint MAY identify either:

1. the directly usable out-of-band service endpoint; or
2. a machine-readable capability document describing the out-of-band service.

If a capability document is used, it 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 or BIP conformance status by itself.

If present, a capability document MUST identify:

• the advertised service type
• a service or profile identifier for the out-of-band protocol or provider flow
• the supported version or versions of that protocol or profile
• the endpoint or endpoints to be used for that out-of-band protocol or provider flow
• the transport and authentication expectations needed to access those endpoints

If present, a capability document MAY additionally identify:

• provider or operator identity
• supported corridor, asset, rail, or environment scope
• onboarding prerequisites
• documentation URI
• other non-YONA operational metadata

A capability document MUST NOT be treated as changing:

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

A VASP MAY use such capability information under local policy to decide whether and how to attempt post-ACCEPT Travel Rule exchange or settlement-instruction 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.

Such assurance material MAY include:

• conformance claims
• conformance reports
• certificates
• provider attestations
• equivalent assurance artifacts

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

YonaAssuranceService does not by itself 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 BIP 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 BIP 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. BIP Conformance Scope

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

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

To claim full BIP 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 basis for making a BIP conformance claim under yona:ruleset:v1.0.

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

1. satisfies all applicable normative requirements in YONA Ruleset 1.0;
2. satisfies all applicable normative requirements in the Base Interoperability Profile (BIP); and
3. passes the applicable normative test cases in the BIP Conformance Test Suite.

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

If a conformance report is produced, it SHOULD state:

• which role or roles were tested;
• the tested interaction scope (pull, push, or both);
• the tested ruleset_id; 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 BIP conformance claim under yona:ruleset:v1.0 is optional. However, any implementation that claims BIP 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 BIP conformance itself.

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

A VASP MAY make a self-asserted BIP 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 BIP 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 BIP 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 BIP conformance under yona:ruleset:v1.0.

6.4 Push-payment-only pilot subset

This subsection defines how a restricted push-payment subset may be described without overstating conformance.

A push-payment-only deployment MAY still be useful for:

• pilot deployments
• early interoperability experiments
• restricted environments

However, full BIP conformance under yona:ruleset:v1.0 requires support for the full baseline interaction model.

A push-payment-only deployment MUST NOT claim full BIP conformance.

Such a deployment MAY instead claim pilot support or push-payment subset support only if those claims are accurate and do not imply full BIP conformance.

A push-payment-only pilot is a restricted subset of BIP behavior covering push-payment authorization only. It excludes YonaPaymentIntentService retrieval and pull-specific cases that depend on a retrieved embedded yona.payment_intent. The pilot does not redefine YONA message semantics and does not create a separate protocol model.

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.