1. Where to Start

1.1 If your institution is implementing the current YONA pilot

Start with the documents that define the pilot's required behavior:

1. YONA Pilot
2. YONA Ruleset 1.0

Then use Reference Messages & DID Examples for illustrative message shapes, DID document examples, and expected patterns. It is helpful for implementation, but it does not define YONA requirements.

The pilot is the current lower-lift path. It is limited to the push-payment authorization interface and is not full YONA conformance.

1.2 If you are expanding into full BIP

After pilot work, move to:

1. YONA Ruleset 1.0
2. Base Interoperability Profile (BIP)
3. YONA Conformance Test Suite
4. Reference Messages & DID Examples
5. YONA Conformance Report Template

If you already completed the standalone pilot for the same implementation version and material configuration, do not re-do the duplicated push-payment subset. Add the remaining retrieval, pull-payment, and other full-BIP work.

2. How to Approach Implementation

2.1 Treat the documents as separate layers

Use the documents for different purposes:

• Ruleset explains YONA semantics and message behavior.
• BIP explains the interoperable discovery, transport, and endpoint profile.
• YONA Conformance Test Suite explains what has to pass for full BIP verification.
• Pilot packages the current push-payment pilot into one place.

Do not try to pull all of that logic into one internal document. Keep the same separation in your implementation work.

2.2 Build around boundaries, not pages

A clean implementation usually separates:

• DID resolution and service selection
• JOSE parsing and signature verification
• message validation
• authorization decisioning
• request/response binding
• replay handling
• repeated-request handling
• transport behavior

Those boundaries matter more than the order of the website pages.

2.3 Start with exact behavior, not convenience abstractions

Do not let helper code silently reinterpret YONA fields or normalize data that needs to stay exact.

Common mistakes come from:

• hashing reconstructed content instead of exact bytes
• mixing push and pull request handling
• treating beneficiary references as local routing instructions
• collapsing replay handling and repeated-request handling into one mechanism

3. How to Think About the Current Pilot

3.1 What the pilot proves

The pilot is there to prove that the push-payment authorization interface works between counterparties.

That means engineers should focus on:

• reaching the correct beneficiary-side authorization endpoint
• producing and validating the authorization messages correctly
• preserving request/response binding
• handling terminal outcomes deterministically

3.2 What the pilot does not prove

The pilot does not prove full BIP support.

It does not cover retrieval or the pull-payment path.

Teams should not treat pilot completion as evidence that full BIP implementation is finished.

4. Practical Engineering Advice

4.1 Keep discovery explicit

Resolve the DID document, identify the correct service entry, and use the published endpoint deliberately.

Do not rely on hidden defaults, fallback endpoints, or local assumptions about what the counterparty "probably meant."

4.2 Keep message handling strict

Validate before acting.

Do not move forward because a message "looks close enough." YONA interoperability depends on strict handling, especially around message type, audience, issuer, identifiers, and binding.

4.3 Keep binding logic isolated

Treat request/response binding as its own implementation concern.

That logic is easy to get wrong when it is buried inside general message parsing or transport code.

4.4 Keep replay and repeated-request logic separate

These are related but different problems.

If you handle them as one thing, you are likely to reject legitimate retries or accept something you should not.

4.5 Keep transport failure separate from authorization outcome

A failed or missing response is not the same thing as receiving a valid signed terminal message.

Engineers should model those cases separately, even though operationally the originator still must not proceed without a valid ACCEPT.

4.6 Keep published endpoints defensible

serviceEndpoint URLs in a DID document are meant to be found, so they are not secret—expect the same untrusted traffic as any public HTTPS API.

Cryptography and strict parsing define what counts as a valid YONA message; they are not a substitute for operational protections (rate limits, web application firewalls, capacity). Mutual TLS or allowlists are optional deployment policy (BIP Section 4.3). This subsection is non-normative.

5. How to Use the Test Material

5.1 For pilot work

Use the YONA Pilot as the testing and reporting basis.

It duplicates the current push-payment subset so that pilot participants can work from one document.

5.2 For full BIP work

Use the YONA Conformance Test Suite directly.

The suite is the full verification basis. The pilot is only the reduced entry path.

5.3 During development

Do not wait until the end to run conformance-style checks.

Test these early:

• exact-byte binding behavior
• wrong-binding cases
• malformed JOSE handling
• duplicate-member handling
• replay behavior
• repeated-request behavior

These are common sources of interoperability failure.

6. Scope Reminder

YONA does not define Travel Rule payloads, settlement instructions, settlement execution, custody, local compliance decisioning, or post-ACCEPT message transport.

Implementers should model ACCEPT as a gate into post-ACCEPT workflows, not as proof that counterparty due diligence, Travel Rule eligibility, sanctions review, or settlement approval has been completed.