SMIFT Protocol 0.1 - Alessandro-Salerno/SMIFT GitHub Wiki

The SMIFT Protocol, or SMIFTP for short, is a set of rules used by clients and servers to communicate on a SMIFT Network. The SMIFT Protocol defines the type and structure of messages, alongside timings, accepted values and other technical details.

Development on SMIFTP 0.1 started on May 12th, 2024. This version defines the basic format for SMIFT messages and a few fundamental primitives.

Messages in this version of the SMIFT Protocol are sent via TCP through an unsecured channel.

Messages in this version of the SMIFT Protocol use UTF-8 encoding and are zero-terminated. Lines are terminated by the CRLF sequence.

Certain terms used in this page may be ambiguous. When reading, keep in mind this table:

SMIFTP is a fully asynchronous protocol. Exchanges generally start with a request from a client and end with a response from another client. The SMIFT Routing Server acts as a middleman between nodes, forwarding messages from one to another. Due to the asynchronous nature of SMIFTP, the Routing Server and clients use the initial request hash, unique transaction ID, and state machines to keep track of requests.

Messages in SMIFTP 0.1 are comprised of a header and a body, separated by an empty line. The message body contains attributes in a STOMP-like syntax. Headers in this version of SMIFTP contain a version phrase, message type and additional attributes.

SMIFT/0.1 <MESSAGE TYPE> <ARGUMENTS>

<KEY>: <VALUE>
...
<KEY>: <VALUE>

Following is an example of a message valid in SMIFTP 0.1

SMIFT/0.1 RESPONSE 500 Hello world

Property-X: hello
Property-Y: world
Timestamp: 2024-05-12 00:00:00

Body attributes can have one of several data types:

Messages can be one of three types

• REQUEST
• RESPONSE
• FORWARD

Requests are initiated by a client looking to communicate with another client and use the following header:

SMIFT/0.1 REQUEST <COMMAND>

Request messages ALWAYS have a Timestamp field in the body. This timestamp is used to store the time and date on which the request was originally generated and is of type TIMESTAMP. This is useful to ensure that message hashes are always different.

The full list of commands can be found in the [dedicated section][#Rquest-commands].

Response messages are either sent from the Routing Server to a requesting client, or from a handling client to the Routing Server. These messages use the following header:

SMIFT/0.1 RESPONSE <CODE> <PHRASE>

Response messages ALWAYS have a Timestamp field in the body. This timestamp is used to store the time and date on which the response was originally generated and is of type TIMESTAMP. This is useful for deferred responses.

Response codes and phrases can be found in the [dedicated section][#Response-messages].

Forward messages are used by the SMIFT Routing Server to forward an incoming request to a handler node. Forward messages differ from request messages in commands and body contents, but use a similar header:

SMIFT/0.1 FORWARD <COMMAND>

Forward messages ALWAYS have a Timestamp field in the body. This timestamp is used to store the time and date on which the request was originally generated and is of type TIMESTAMP. This is useful for deferred requests.

The full list of commands can be found in the dedicated section.

Request messages can be used to issue the following commands:

This is the first message a client sends to the SMIFT Routing Server after establishing a connection.

The SMIFT Routing Server can reply with one of the following responses: 200, 300, 301, 302.

This command can only be issued by authenticated clients.

The server can reply with one or more of the following responses: 110, 111, 112, 210, 301, 302, 303.

NOTE: 112, 210 responses may be deferred due to settlement and clearing delays.

This command can only be issued by authenticated clients.

The server can reply with one of the following responses: 113, 211, 301, 302, 303.

NOTE: 211 responses may be deferred due to settlement and clearing delays.

Response messages can be classified as:

• Progress
• Complete
• Error

The second digit in the response code identifies the response's subtype. Response subtypes are common across response classes

Progress responses use codes 100-199 and are used to communicate updates about a transaction.

This response is generated after a transfer request has been accepted (but not settled) by the handler node.

This response is generated after a transfer request has been settled by the handling node.

This response is sent after the SMIFT Routing Server has authorised the cancellation of a transfer, but BEFORE the authorisation by the handling node

Complete responses use codes 200-299 and are used to indicate that a transaction has been completed. Once a Complete response is sent, the transaction, if present, is considered closed.

This message is sent by the SMIFT Routing Server as a positive response to an AUTHENTICATE request.

This response is sent after a transfer has been settled by the handling node and credited to the final user.

This response is sent after a transfer has been cancelled by the handling node.

Error responses use codes 300-399 and are used to communicate a failure. Once an Error response is sent, the transaction, if present, is aborted.

This response is sent by the SMIFT Routing Server if a client is using an unsupported version.

This response is sent if an unauthenticated client is trying to execute a request, or if a node refuses a request bases solelly on the client's identity (for example, in the case of econoimc sanctions).

This response is sent if the initial request contained syntax errors.

This response is sent if one or more attributes of the initial request are invalid (i.e. uknown destination server, currency, account number, etc).

Forward messages can be used to issue the following commands:

This command is issued by the SMIFT Routing Server and sent to a handling node for settlement.

This command is issued by the SMIFT Routing Server and sent to a handling node to complete the cancellation.

This command is issued by the SMIFT Routing Server and sent to the final handling node to credit the final user's account.