Secure Asset Transfer Protocol (SATP) Implementation Guide

1.1. Scope and Limitations

The initial implementation scope is a direct transfer between two gateways, one test asset per transfer, and controlled network adapters. The test peer should implement both sender and receiver roles. It should support invalid-input and failure injection as well as successful transfers.¶

Production operations, high availability, general gateway discovery, complete regulatory workflows, arbitrary ledger integrations, and performance qualification are outside the initial scope. Mock networks can demonstrate decisions made by the peer, but cannot establish a real ledger's finality or cross-system economic guarantees.¶

Chaining bilateral transfers does not by itself establish atomicity over an entire multi-hop route. An implementation studying that case should identify its additional coordination protocol and failure assumptions. This guide does not define that protocol. Similarly, a successful two-phase exchange under stated assumptions does not prove unconditional termination or automatic recovery after every possible failure.¶

1.2. Specification Baseline and Pending Changes

The following revisions form the documentary baseline for this draft. The section numbers cited in this guide refer to these revisions.¶

Core revision -17 specifies an HTTPS and JSON baseline. The October 2026 discussion in [TRANSPORT-DISCUSSION] proposes separating transport properties from gRPC and HTTP mappings. That discussion records a change plan, not an already published replacement for the requirements of revision -17. Guidance about transport separation in this document anticipates that direction without defining a standard gRPC binding.¶

When a later revision is selected, implementers should update the requirements-to-test mapping and record changes in accepted messages, security processing, and failure behavior. An editor's copy should be identified by a commit, not merely by a moving "latest" URL.¶

3.1. Separation of Responsibilities

A small implementation can use the following components without adopting a large gateway framework.¶

The Core engine should not depend on a particular HTTP handler or RPC framework. A useful local API accepts validated input and current state, then produces a proposed next state and explicit actions. The surrounding code records decisions, executes backend actions, and records their outcomes. This design makes the same decision logic testable without a network connection.¶

Separating actions does not make a local database and a remote ledger atomic. The adapter should retain backend operation identifiers and allow the harness to query whether an operation happened when an outcome is uncertain. Tests should include a crash after backend execution but before the journal records success.¶

3.2. Network Adapter and Journal

For the initial experiment, the adapter should expose asset inspection, source locking, source extinguishing, destination creation under gateway control, and final assignment to the beneficiary. The selected network determines the actual operations and proofs. Any cleanup operation should state its preconditions and irreversible boundaries.¶

The journal should associate the TCID, Session ID, gateway roles, asset identifiers, message type, relevant sequence and hash information, signature verification result, backend operation ID, and before/after observations. Persisting a decision before sending its corresponding message reduces uncertainty, but is not a complete recovery protocol.¶

The harness should independently inspect backend state rather than rely only on the gateway's success response. In the controlled asset model it should check that the same transferable value does not become spendable by both the originator and beneficiary. Temporary destination assets held by G2 should be distinguished from assets available to the final beneficiary.¶

4.1. Successful Bilateral Transfer

The following sequence summarizes Sections 8 through 10 of [SATcore]. Message names are suffixes of the namespace urn:ietf:params:satp:core:msgtype:. The state observations are test boundaries rather than new wire states.¶

1. Stage 1 exchanges transfer-proposal-msg , proposal-receipt-msg , transfer-commence-msg , and ack-commence-msg , alternating between G1 and G2. The peers establish the proposed transfer and its commencement.¶

2. Stage 2 sends lock-assert-msg from G1 after the source lock. G2 validates the claim, records it in NW2 as depicted in Core Figure 2, and returns assertion-receipt-msg .¶

3. Stage 3 sends commit-prepare-msg from G1. G2 creates the destination asset under its own control and sends commit-ready-msg .¶

4. G1 extinguishes the source asset and sends commit-final-msg with the relevant evidence. G2 verifies it, assigns the destination asset to the beneficiary, and returns ack-commit-final-msg .¶

5. G1 records completion and sends commit-transfer-complete-msg to G2.¶

The implementation should compare this sequence against the normative field descriptions, not copy draft examples without checking them. In particular, creation under G2's control and assignment to the beneficiary are distinct observations in this baseline.¶

4.2. Validation and Cryptographic Processing

For each message, validation should use that message's own schema and the current session state. Useful checks include the authenticated counterpart, expected message type and sequence where defined, transfer association, applicable expiration, signature, claim format, and relevant hashes. A message that decodes successfully can still be invalid in the current state.¶

The signed-message and cryptographic baseline is described in Section 5.2 of [SATcore]: peer messages are protected with JWS [RFC7515], with ECDSA P-256 and SHA-256 (ES256 [RFC7518]) as the baseline. The standalone burn assertion in Section 10.3 is also signed independently; verifying only the enclosing message does not replace verification of that claim. The implementation should distinguish transport keys, gateway message-signing keys, and network evidence keys. A key received in a message is not automatically a trusted identity.¶

Hash validation should be field-specific. Proposal Receipt, for example, has its own claim-hash and timestamp semantics; the guide does not add a previous-message hash to every message. The test profile should specify the exact bytes used for each hash and signature, including any envelope exclusion, serialization, and encoding rule that needs clarification. A semantic JSON comparison is insufficient to establish byte-level signature interoperability.¶

4.3. Errors, Abort, and Uncertain Outcomes

Core error handling should follow Sections 10.6, 10.7, and 11 of [SATcore]. Protocol failure, an application-requested abort, and a connection failure are distinct events. For the -17 HTTP baseline, Section 11.3 describes error representations using application/problem+json and [RFC9457], with SATP-specific information. These should not be replaced by invented private Core error codes.¶

An abort ends the session exchange, but its effect on assets depends on the point reached. The implementation should evaluate the irreversible boundary described in Section 11.5 before attempting cleanup. A timeout after extinguishing the source asset does not justify recreating it or assuming that the destination assignment failed.¶

Section 10.8 of Core revision -17 does not provide session recovery or resumption. The proposed peer can preserve evidence and expose an inconclusive outcome for operator diagnosis. Any additional recovery exchange should be separately identified and tested as an extension. A Hermes recovery facility is not automatically a Core -17 requirement.¶

The initial harness should disable configured application-level retries for state-changing operations, document lower-level retry behavior, and then test explicitly configured retransmission scenarios. Duplicate inputs should be checked before repeating backend effects. This advice does not create a retransmission protocol absent from the baseline.¶

4.4. Clarifications to Track

Revision -17 contains points that independent implementations should raise for clarification. These include the ack-prepare-msg entry in Section 5.3.2 versus commit-ready-msg in Section 10.2, and mintAssertionFormat in a field description versus mintAssertionClaimFormat in an example. Example syntax and spelling also need validation before becoming fixtures.¶

The exact serialization and hash boundary, and the interaction between general lock-release wording in Section 11.2 and the post-commit boundary in Section 11.5, deserve explicit review. A test profile can record a provisional interpretation to reproduce an experiment, but this guide does not settle these specification questions or declare a new wire format. Cases affected by unresolved choices should identify that fact in their result.¶

5.1. Published HTTP Baseline

For Core revision -17, the HTTP adapter should exercise the specified HTTPS POST, TLS 1.3 [RFC8446], JSON [RFC8259], and application/satp+json behavior, while handling the error representation described in Section 4.3. It should retain the distinction between transport delivery, protocol acceptance, and completion of a backend operation.¶

The profile should document routing, status handling, response correlation, connection timeouts, size limits, credential placement, and any use of mutual TLS. It should identify which choices are explicit in Core and which need agreement for the experiment. This guide does not assign a new standard HTTP endpoint or negotiation mechanism.¶

5.2. Experimental gRPC and Hermes Compatibility

A gRPC experiment should keep the Core domain model separate from its service definitions and serialization. The profile should name the service methods, unary or streaming behavior, metadata placement, deadline and cancellation handling, and status/error mapping. A gRPC status should not erase a signed SATP protocol error. Cancellation of a call also does not roll back a backend operation already performed.¶

Native gRPC, gRPC-Web, and Connect are different protocol mappings. Native gRPC normally uses HTTP/2; an HTTP/1.1 gRPC-Web endpoint is not interchangeable with it. The inspected [HERMES] snapshot constructs gRPC-Web transports for the Core stages in gateway-orchestrator.ts. The adapter should match the actual counterpart's endpoints and protocol. That observation is not a claim that Hermes defines the standard binding.¶

The harness should distinguish a Hermes compatibility test from a Core -17 HTTP conformance test. It can share the same domain engine, while the compatibility adapter records the counterpart's schema, paths, metadata, and serialization. Using a supplied .proto file is permitted for interoperability, but adopting its state-machine implementation would weaken the independence of the test peer.¶

The inspected Hermes jws-interceptors.ts signs Protobuf binary content and carries the JWS in the satp-signature header. Cross-language fixtures should therefore establish the exact signed bytes before a full transfer is attempted. [PROTO-SERIALIZATION] explains why deterministic Protobuf output is not a canonical representation across all schemas, runtimes, and changes. Re-encoding received data can change the bytes used in signature verification.¶

The experiment should cover default and absent values, unknown fields, maps, byte fields, and JSON-to-Protobuf conversion. A decision to use a particular canonical representation is a mapping choice that needs agreement; this guide does not silently replace the counterpart's representation with JCS. JCS requirements for Registry are discussed separately in Section 7.1.¶

gRPC includes retry mechanisms [GRPC-RETRY]; selecting it does not provide exactly-once application effects. Retransmission and duplicate suppression remain explicit subjects for the harness.¶

5.3. Other Encodings

CBOR/COSE and other representation experiments should have separate mapping identifiers, schemas, and test vectors. They are not presented here as interchangeable alternatives to the -17 JSON/JWS baseline. This revision does not define CBOR integer-key assignments or imply that such assignments already exist in Core.¶

6.1. Transfer Context and Asset Binding

A useful local model separates four identifiers:¶

• TCID identifies the transfer context linking the transfer intent, participants, assets, and gateways.¶

• Session ID identifies a particular Core execution associated with that context.¶

• TAR ID references information held by an Artefacts Registry.¶

• DAR ID identifies an asset record managed by the represented network.¶

These identifiers should have separate fields and validation rules. A TAR reference does not replace the source network's DAR ownership and transfer authorization checks. Similarly, assigning a DAR to a TC during Setup is not itself the lock asserted in Core Stage 2. The ledger adapter should expose these operations separately so tests can observe the distinction.¶

Section 2 of [SETUP] describes creating a context, propagating its ID to the beneficiary application, preparing the destination network, binding the gateways, and starting Core. Section 4 illustrates multiple sessions associated with one context. This example does not define a session recovery protocol. An implementation should preserve the association for diagnosis without treating a new Session ID as permission to repeat an irreversible asset operation. Core recovery limitations remain those of the selected revision of [SATcore].¶

6.2. A Minimal Setup Interface

The following names describe a possible experimental interface. They do not assign RPC methods, HTTP routes, message schemas, or error codes. Some operations belong to applications or network adapters rather than to a gateway service; a test driver can coordinate them without changing the responsibilities described in [SETUP].¶

A concrete experimental profile should specify who can invoke each operation, what constitutes successful completion, how duplicates are identified, and which actor can cancel an incomplete Setup. It should also specify how concurrent updates are serialized. For example, a transactional compare-and-set on the local context record can prevent two successful BeginTransfer calls from allocating competing active sessions. This local mechanism is not a new Core concurrency requirement.¶

6.3. Checking Entry into Core

Section 3 of [SETUP] gives five prerequisites: an unambiguous context held by the originator application; source-network awareness of the assets and TC; a gateway pair bound to that TC; beneficiary awareness of the incoming assets; and destination-network preparation for that beneficiary and TC.¶

The proposed implementation should turn each prerequisite into a separate check with an identifiable source of evidence. BeginTransfer should evaluate a consistent snapshot of the evidence, authenticated participant identities, asset set, and context expiry. It should record which check prevented entry, without exposing sensitive beneficiary information. An application acknowledgment alone should not be mistaken for a network's completed preparation.¶

The following is a synthetic local diagnostic record. Its field names and values are not a standardized Transfer Context or a SATP wire payload.¶

{
  "contextHandle": "example-tc-42",
  "coreSessionHandle": null,
  "sourceDarHandle": "example-source-asset-42",
  "tarVersion": 3,
  "entryChecks": {
    "originatorContext": true,
    "sourcePrepared": true,
    "gatewaysBound": true,
    "beneficiaryAware": true,
    "destinationPrepared": false
  },
  "eligibleToStart": false
}

6.4. Consistency, Expiry, and Setup Tests

As an experimental protection against time-of-check/time-of-use changes, the local context should retain the registry identity, TAR ID, selected version, content digest, and applicable policy version. Before entering Core, the implementation can check that both gateways accepted the same snapshot. A changed snapshot should trigger explicit reconsideration of Setup rather than silently changing the meaning of an active transfer. This proposal does not define a new on-wire negotiation field.¶

An expiry policy should distinguish abandoned preparation from an active Core transfer. An elapsed timer or lost response does not demonstrate that a remote asset operation failed. In particular, a Setup expiry should not automatically unlock or recreate assets after commitment has begun. The implementation should retain the relevant evidence and use only procedures justified by the Core revision and ledger semantics.¶

Tests should omit each entry prerequisite separately, substitute a gateway or beneficiary, submit concurrent contexts for the same DAR, repeat BeginTransfer, change a TAR after binding, and restart a gateway between preparation and entry. The expected outcomes should include both the application-visible decision and the observed network state. These tests are proposed coverage; no successful execution is claimed here.¶

7.1. Transport, Authentication, and Trust

[REGISTRY] specifies JSON API calls over HTTPS, supports GET and POST, describes JWS signatures [RFC7515], and identifies ES256 and JSON Canonicalization Scheme (JCS) [RFC8785] support. It also describes JWT/OAuth-based client authentication. These are properties of the Registry draft: a possible gRPC mapping for Core does not replace API3's specified HTTP mapping.¶

A test deployment can select TLS 1.3 and a small, preconfigured set of registry identities and client credentials. This choice simplifies reproducibility without redefining the Registry draft's transport baseline. Certificate validation, accepted signing keys, token issuer and audience, operation authorization, and trust in the returned artefact should be evaluated separately. A valid registry certificate authenticates an endpoint; it does not independently prove asset ownership or the truth of a registered statement.¶

For reproducible signature checks, the test profile should record the protected headers, exact signed content, canonicalization boundary, signature representation, and key selection rules. Sorting JSON object keys with a language's default serializer is not a substitute for JCS. Tests should verify signatures across implementations using fixed inputs and public test keys, including Unicode, numeric, and escaping cases. Request authentication and response authenticity should both have documented checks; an omitted response-signing detail should be recorded as an unresolved mapping question rather than silently invented.¶

7.2. Records, Versions, and Caches

The Registry draft describes append-only history: update registers a new version, and the operation named deletion archives a TAR. A test registry should retain earlier versions and record archive events rather than physically erasing the history used to explain a transfer.¶

A minimal deployment can begin with a pre-populated, read-only registry and then add create, version append, and archive operations. This sequence allows Setup tests to proceed before a complete registry implementation exists. The report should identify the supported subset. For asynchronous creation, the adapter should distinguish a temporary receipt from the resolved TAR identifier and should avoid starting a dependent transfer on an unresolved receipt.¶

The suggested snapshot protection in Section 6.4 should also govern caching. A useful local cache key contains registry identity, TAR ID, and version; stored digests and provenance allow a caller to verify that the selected record has not changed. Fetching "latest" repeatedly during an active transfer risks mixing decisions based on different records. Archive, revocation, and policy-change handling should be explicit; a pinned historic snapshot is an audit reference, not a reason to ignore a new authorization decision.¶

The Setup diagram's registration of a TC does not define a complete TC storage API or make a TC equivalent to a TAR. Implementations should identify where contexts are persisted and how they reference TARs. If an experimental deployment stores both in one database, their data models, access rules, and version histories should remain distinguishable.¶

7.3. Errors and Registry Tests

Several Registry error definitions remain unfinished in revision -01. An adapter can use local outcomes such as not-found, unauthorized, unsupported-version, invalid-signature, archived, conflict, and temporarily-unavailable, provided the test profile identifies them as local classifications rather than registered protocol error codes. Retries should follow the operation's defined duplicate-handling rules; loss of a create response does not establish that creation did not occur.¶

Registry tests should cover rejected credentials, unauthorized version append, incorrect registry identity, modified content, mismatched digest, stale cache entries, changes between Setup and Core entry, repeated create/update, receipt resolution, and historical lookup after archive. Tests should observe persisted versions as well as returned responses. Draft examples should undergo syntax and semantic review before becoming expected-output fixtures: a displayed update response is not evidence of a passing version-transition test.¶

8.1. Three Separate Assessments

An experiment should distinguish the following assessments. Passing one does not establish the others.¶

The profile should identify its scope without claiming an IETF certification. A Hermes compatibility profile can be useful even if its mapping differs from the -17 HTTP baseline, provided that distinction is reported. Conversely, an unsupported extension is not evidence that the counterpart fails Core conformance.¶

Profile names and test configurations are local artifacts, not standardized capability advertisements. Select profiles out of band for the initial experiment. An automatic negotiation mechanism would need its own specification and downgrade analysis.¶

8.2. Test Case Structure and Observations

A reusable case should contain a stable identifier, assessment type, source requirement or experimental rule, preconditions, stimulus, expected peer decision, expected backend effects, observation points, and permitted timing assumptions. It should also identify the peer roles and the fixture version. An expected result should come from the specification or explicitly stated experiment, not solely from a trace captured from the counterpart.¶

For a complete transfer, observe both gateways and both networks. For a rejection, observe that the forbidden operation did not occur. For an uncertain outcome, preserve enough evidence to distinguish a lost response from a backend operation that was never executed. Time-bounded observations should record their bound rather than imply a universal liveness guarantee.¶

Record PASS or FAIL only when the expected result and observations are sufficient. Use UNSUPPORTED for an absent feature, INCONCLUSIVE when evidence or the specification does not support a decision, and NOT-RUN for a planned case. These are local report statuses, not protocol errors. A report should state its coverage denominator and excluded cases; one aggregate pass percentage is insufficient to describe interoperability.¶

8.3. Minimum Coverage

The following groups provide an initial test inventory. They are recommended coverage, not additional SATP conformance requirements.¶

Each delivery failure should be injected at a named boundary: before receipt, after validation, after backend execution, or after persistence but before response delivery. Random fault injection can supplement these cases after deterministic tests provide a reproducible baseline.¶

Transport failure tests should include authentication errors, wrong protocol mapping, deadline expiry, inconsistent HTTP error status, and malformed signed errors. A transport success response alone is not evidence of an accepted SATP message or a completed transfer.¶

8.4. Both Roles and Independent Oracles

The initial matrix should include independent-peer sender to Hermes receiver, and Hermes sender to independent-peer receiver. Two instances of the new peer are useful for development but should be reported as same-implementation tests. Optional module results should name the actual counterpart; self-tests should not become cross-implementation claims when Hermes does not support the module.¶

The harness should compare observed results with a small independently defined transition model and direct network observations. Sharing wire schemas and public fixtures can improve compatibility. Sharing the counterpart's state engine or treating every counterpart response as the expected answer would reduce the value of an independent test.¶

Failure triage should distinguish a specification ambiguity, a counterpart mismatch, a new-peer defect, a transport mismatch, and an unsupported feature. Evidence for a specification issue should include the relevant revision and section, a minimal input, the competing interpretations, the observed effect, and a proposed clarification. Avoid assigning implementation blame before identifying the source of the expected behavior.¶

9.1. Initial Counterpart and Implementation Status

[HERMES] is a public implementation selected as an initial interoperability counterpart. This guide does not claim that a survey has established it to be the only SATP implementation, or that a particular release implements every requirement of the baseline. The referenced snapshot is evidence for the compatibility investigation, not a validated compatibility declaration.¶

The independent peer described here is a proposed implementation. This revision assigns no repository or release to it, and reports no completed protocol or interoperability test run. The procedures in this guide describe how to conduct and report future experiments.¶

9.2. Language and Development Environment

Go is a practical initial target for the proposed peer: explicit data types, the standard HTTP and cryptographic libraries, a small executable, and built-in testing support suit a controlled gateway and test driver. Connect-Go [CONNECT] provides a way to exercise native gRPC and gRPC-Web while retaining an explicit choice of mapping. This is an engineering choice for the experiment, not a language requirement for SATP. Framework version and default protocol selection should be pinned.¶

A minimal repository can separate the Core engine, codecs, transports, network adapters, journal, Setup and Registry modules, fixtures, and command-line test driver. Protobuf generation can use protoc or Buf with fixed generator versions. The initial deployment can run on Linux or WSL2 and use Docker Compose to start the counterpart and mock networks. It need not introduce Kubernetes, multiple production ledgers, or a large workflow framework.¶

Python is also a reasonable option when the team is substantially more experienced with it, particularly for scenario modeling. Choosing a native gRPC library is not sufficient to establish compatibility with a gRPC-Web counterpart. The same signed-message feasibility check and role matrix should precede a larger Python implementation.¶

9.3. Incremental Development Gates

1. Capture the baseline and counterpart contract: specification revisions, commit, schemas, paths, credentials, protected content, and expected message semantics.¶

2. Exchange one protected message and response across languages. Compare signed bytes and verify signatures and hashes. Include a negative case before expanding the protocol implementation.¶

3. Implement the Core engine and mock networks. Exercise success, rejection, and irreversible-operation boundaries without depending on a remote gateway.¶

4. Run both roles against the counterpart, keeping HTTP conformance and Hermes compatibility results separate.¶

5. Add Setup entry checks and a pre-populated Registry; then add registry version, signature, and archive scenarios.¶

Each gate should produce reviewable fixtures, traces, and a coverage report. Tests that depend on unresolved choices can remain INCONCLUSIVE while unaffected cases proceed. A complete production gateway is not a prerequisite for providing useful feedback to the working group.¶

9.4. Reproducibility and Revision Tracking

Publish implementation commits, build instructions, fixture versions, container digests when used, public test credentials, and the manifest needed to repeat an experiment. Live private credentials and production data do not belong in that package. A counterpart update should trigger a documented comparison of schemas, protected bytes, and required behavior rather than an unreviewed change to expected outputs.¶

The guide should track every substantive source change to affected implementation modules and tests. Changes to extensions should not silently change the Core baseline. An issue log can connect each open question to its provisional profile setting and eventual resolution.¶

10.1. Identity, Keys, and Representation

Authenticate gateway and registry endpoints, then separately establish the authorized message signer and the meaning of supplied evidence. Keep transport authentication, message authentication, asset authorization, and ledger proof verification as distinct checks. An attacker-controlled key in a syntactically valid JWS should not become a trust anchor merely because it verifies that same JWS.¶

Fixtures should identify accepted algorithms and key purposes. Tests should reject algorithm substitution, mismatched identities, corrupted signatures, and incorrect encoding. Serializing and verifying structured content across languages needs an agreed byte contract, particularly when a transport adapter changes the representation.¶

10.2. State, Replay, and Irreversible Actions

Bind accepted inputs to the expected session, context, role, and state using fields and checks supported by the selected mapping. Duplicate detection should precede repeated backend effects. A persistent operation association helps diagnose whether a response was lost after an action, but does not authorize an undefined recovery exchange.¶

Expiry, connection loss, and application abort should not be treated as proof that an irreversible operation did not happen. Cleanup should be justified by asset state and the selected protocol's abort semantics. Unknown outcomes should retain evidence and avoid actions that could make value available to both parties.¶

Setup should authenticate the participants and gateway pair associated with an asset set. A context substitution or change to a referenced TAR should be visible before Core entry. Both gateways should validate the context and artefact snapshot used for that entry.¶

10.3. Exposure and Availability

Treat configured gateway and registry endpoints, artefact content, and asset-operation arguments as untrusted input. The controlled experiment can use explicit endpoint and operation allowlists. Limit decoding depth, message and claim size, signature work, pending contexts, and request duration. Registry lookup should not enable unrestricted network access or arbitrary code execution.¶

A valid TLS connection or Registry response does not prove that an asset exists, belongs to the requester, or has the asserted finality. Those checks belong to the relevant network and evidence model. Availability or replication of a registry also does not remove the need to establish trust in the artefacts it serves.¶