# High-level comments and caveats of review

The satp WG appears to be relatively recently formed. It is chartered to develop standards that address interoperability problems in digital asset networks. This is a technology domain I am not familiar with, so please excuse review comments that arise because of that.

draft-ietf-satp-core-00 was only adopted to the WG in April 2023. The position of "Not ready" is, hopefully, not unexpected at such an early point in the standardization process. However, what is not clear to me, at the outset nor after review, is whether the document is based on existing industry practice or if its more of a greenfield solution that is expected to change a lot during the process. In part, my lack of clarity on this arises from the document intended status being marked as Informational, which could imply its based on some external entities documentation. If that's not the case, perhaps an intended status of Proposed Standard is more appropriate. Either way, the specification as written has several aspects that leave important interoperability questions unanswered. That makes me wonder whether there is implementation activity ongoing in parallel because there's practical issues that would have to have been solved in order for the interactions to succeed.

I read the entirety of draft-ietf-satp-core-00 in isolation before looking into the details of the WG or other related documents. This document defines a protocol for interactions between a number of actors. It dedicates significant amounts of text to explain the conceptual model, which was appreciated on first read through. However, only afterwards did I realise that draft-ietf-satp-architecture-00 exists - its purpose to define a Secure Asset Transfer interoperability Architecture. There is significant overlap and duplication between these documents at it was rather surprising not to even see the protocol spec refer to its architecture. My recommendation is for the authors of these specifications to collaborate in order to minimise the duplication,  with one outcome making the protocol specification clearer to review.

This is an HTTP directorate review, so that's where I have attempted to focus my review. The document has editorial nits beyond those already mentioned. I trust the authors will address these in good time and have omitted them from the review comments.

# What elements of the protocol are HTTP and what aren't?

The overriding sense I have after reading the document a couple of times is that it isn't clear where HTTP is used in a conventional sense vs. where pieces of HTTP are being used as a convenience or a crutch. This plays a significant part in attempting to review it from an HTTP directorate perspective. 

In simple terms, my takeaway is that there are a number of stateful interactions that involve passing JSON-formatted messages between endpoints. This is framed as three different APIs (Type-1, Type-2, and Type-3). The specification details the formats of these messages but I found it confusing how it is intended for those messages to be exchanged between endpoints. One interpretation, which seems unlikely, is that this is a new application protocol entirely and that for each API, it is expected for there to be a TCP connection with TLS atop, and messages are sent over the wire as a stream of bytes carrying a textual serialization of JSON messages. However, another interpretation based on section 4.3 is that these are HTTP-based APIs (named as REST APIs) and so would operate pretty much in that vein.

If we follow the line of HTTP-based APIs, then it would be reasonable to expect these JSON messages are exchanged as message content. Where my confusion arises though is because some messages themselves are defined to carry some HTTP semantics. For instance, Section 5.2 defines the SATP message format for (I think) the Type-1 API. It contains an "Action/Response" field, described as "GET/POST and arguments (or Response Code)". This is simultaneously both restrictive (constrained methods) and incredibly flexible ("arguments" is not defined anywhere in the document). Defining the means to express HTTP within JSON this way raises serious concerns about ambiguity, interoperability and maintenance. It is unclear if this is an attempt to subset HTTP or to support the full range of HTTP semantics and their extension points. I'm left wondering why the Type-1 API doesn't just leave HTTP aspects to HTTP proper, and have the JSON carry the SAT information that is important. Some examples related to this API might help clarify how it is intended to be used. Perhaps what you're trying to define is HTTP message encapsulation, whereby an application sends an instruction (via HTTP) to the local gateway, which decapsulates it and sends it onwards to the remote gateway - and vice-versa. If that's the case it would be clearer to say so. And it raises the question about whether you should be defining your own encapsulation format or seek prior-art in this space.

The other API types don't seem to suffer from similar problems. Section 8.2, for example, details a Transfer Commence Message, which includes a message type defined within its own namespace - urn:ietf:satp:msgtype. My reading is that this is used in API Type-2, the interactions between gateways. The document illustrates the exchange with an example. This opens other questions, that affect the whole document, for a few reasons:

* "the client makes the following HTTP request using TLS" - this is common theme where TLS is mentioned repeatedly. Realistically, the requirement is probably that interactions need HTTPS, which would allow any suitable version - HTTP/1.1, HTTP/2, HTTP/3 or whatever might come in the future. This relates to section 5.6.1, which states "TLS 1.2 or higher MUST be implemented". Requiring better versions of secure protocol is ok, but there seems a little room for improvement in this area to make sure it can support breadth and evolution.

* "Authorization: Basic awHCaGRSa3F0MzpnWDFmQmF0M2ZG" - its not clear why this authorization header is included or how the endpoints arrived at the decision to use the basic scheme. Is it important?

* "Content-Type: application/x-www-form-urlencoded" - but the POST content is JSON. Is it really the intention that the SATP messages can be serialized into either JSON or as query parameters? That's not necessarily a bad thing but it raises several questions the document should be clearer on. For instance, are there any interop problems that might arise due to transforms between those formats?

# Issues within the message formats themselves

I find the "Credential" aspects unclear or underdefined. One message includes a field called "Credential Profile", elsewhere prose refers to "Credential Scheme".

"Application Profile" also seems similarly underfined. An example is provided along with, I presume, example HTTP fields. Its not clear to what parts of the SAT protocol this would apply. The fields also use an X- prefix, which is deprecated per RFC 6648.

# Referencing problems

Overall, the document is lacking sufficient references. 

There are no internal backward or forward references. For a document that weighs in at 29 pages, that's going to impact the readability and comprehension. Some of that problem go away if the authors can dedupulicate text into the architecture document. However, then there's an even bigger need to ensure cross-references are in place to aid the reader.

This leads on to the larger problems with the normative and informative references. There are several normative requirements in the text that relate to other IETF documents that are not listed as normative references. Most importantly, from an HTTP perspective, it cites RFC 2616 which is obsolete. Where HTTP semantics are referenced, RFC 9110 should be used.

RFC 7519 (JSON Web Token) is listed as a normative dependency but doesn't appear to relate to anything in the text.

# Summary

This seems to be a new draft in a young WG, so it is understandably a bit raw. There are parts of the document that could make much more clear; I think that is mostly a straightfoward editorial activity. My comments might be based on incorrect insights drawn as a result of the current document state. However, if they remain, there are some fundamental HTTP-related design issues that do need to be addressed over the long term. For instance, the possibility that this document is defining a new/custom HTTP encapsulation format is something that needs deeper discussion and engagement.