Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Impel's ISO 20022 API uses Smart Contracts on the XDC Network
Because the XDC Network is a fork of Ethereum, it is EVM compatible and also allows for smart contract functionality. Impel's ISO 20022 API's smart contract. The smart contract stores all of the committed proofs and acts as an escrow until every participant approves the terms of the proof.
(1) When a proof is to be committed, one party gathers all info, requests signatures, and creates and commits a proof proposal (1), attaching collateral (if required).
(2) Then an event is published by the contract. Other participants can listen to this event and validate the proof proposal.
(3) If the validation is successful they can approve (2) the proposal, attaching collateral (if they should). If validation fails they can reject it.
(4) If the agreement is not met at specific designated time (defined by the creator) or if transaction is rejected, the attached collateral will be returned back to the sender.
Financial messages exchanged between parties may contain digital assets in the messages payload, therefore only the net settlement amount is exchanged between participants.
Impel's ISO 20022 platform architecture explained in detail
Main components of Impel's ISO 20022 API:
Gateway Service
Identity Service
Smart contract functionality
Multiple messaging protocols
Together, all of these form a distributed, permissioned topology that leverages the XDC Network's blockchain DLT capabilities to meet modern application development requirements for financial messaging.
A Client is a software application's coding languages include Java, Typescript, C#; and uses Impel's ISO 20022 API to send and receive messages via a Gateway Service node. The Client sends a message to a Gateway Service node and then receives a responding message about subsequent processing events.
A Gateway Service is an Impel ISO 20022 platform node that is dedicated to and used by a single client application to process messages and events. The Gateway Service processes incoming and outgoing messages to/from a Client.
Messages are shared between Impel ISO 20022 Gateway Service nodes through message channels. A message channel is created for each Gateway Service node pair; exchanging messages with each other, in order to apply collateral netting on a Proof.
Message is one of the core domain models that holds information about financial messages like ISO 20022, and can optionally attach digital assets as collateral in the message's payload.
A Proof is a core domain model of Impel ISO 20022 platform and is used to group messages from a Message Channel between two platform nodes and to commit them onto the XDC Network's blockchain DLT in batches as a Proof.
The Identity Service is a service used as a registry of Impel's ISO 20022 platform nodes.
Impel's ISO 20022 API platform Smart Contract stores information about all the Proofs committed to the XDC Network's blockchain's DLT. It is also responsible for settling digital asset collateral between participants and acts as an escrow account.
A Client XDC Network wallet address is an account that stores digital assets (XDC or XRC-20 tokens like the US+ stablecoin) and used to send or receive the Proof's digital asset(s) as collateral.
Impel's ISO 20022 API uses a Layer 2 security solution
Layer 2 is a collective term for solutions designed to help scale your application by handling transactions off the Ethereum Mainnet (Layer 1) while taking advantage of the robust decentralized security model of Mainnet.
Layer 2 solutions are built on top of a Layer 1 blockchain DLT protocol (like the XDC Network) to utilize security on a private layer to protect the data from being made public on the public decentralized blockchain. It also lowers transaction costs by combining multiple off-chain transactions into a single message, and also increases transaction speed with the use of data rollups.
Increased transactions per second greatly improve user experience, and reduce network congestion on Mainnet Ethereum
Transactions are rolled up into a single transaction to Mainnet Ethereum, reducing gas fees for users and making Ethereum more inclusive and accessible for people everywhere
Any updates to scalability should not be at the expense of decentralization or security – layer 2 builds on top of Ethereum
There are application specific layer 2 networks that bring their own set of efficiencies when working with assets at scale
Impel's API utilizes a tremendous strategy for sending ISO 20022 financial messages over the XDC Network through an API that permits advanced security and complex data handling. Furthermore, Impel's Layer 2 functionality allows financial messages to be sent without interruption or exposure to a third party.
Our ISO 20022 API's Layer 2 solution is a better fit for meeting the needs of financial institutions using our financial messaging platform, as we have a modified version of the state channels Layer 2 scaling pattern, allowing for a smarter, more secure solution.
Overview and schema of the ISO 20022 API's identity service
The identity service holds information about all of the gateway nodes operating on Impel's ISO 20022 API platform.
Operating as the brains of the ISO 20022 API, the identity service allows very gateway node the ability to accurately and securely route financial messages through Impel's platform from point A to point B by requesting data from other parties, like their BIC (Bank Identification Code), gateway URL, XDC wallet address, certificate, as well as providing the ability to move digital asset collateral from wallet to wallet.
When new gateway node is added to Impel's ISO 20022 API platform, it will be registered via the identity service.
Ethereum's describes Layer 2 as follows:
Ethereum lists the benefits:
Party | Description |
---|
BIC | Business Identifier Code |
Name | Name of the entity |
Gateway URL | The node's gateway URL |
Certificate | Used when signing gateway messages |
Address List | List of XDC wallet addresses |
Network | The blockchain network where the wallet addresses reside, e.g. XDC Network) |
The key aspects and components of Impel's ISO 20022 API
Send and receive financial messages between clients and other gateways
Committing message proofs onto the XDC Network's blockchain
Allowing digital assets such as the XDC Coin or US+ stablecoin to be included in the message's payload for instant settlement, without the need for traditional nostro/vostro accounts, nor the Central Banking system
Message
Proof
Event
Impel's ISO 20022 API is an event driven system that contains defined events
An event represents a lifecycle state of a message and proof object. Learn more about event (computing) here on Wikipedia.
Description | |
---|---|
id
Platform identifier
type
Type of an event e.g. (MESSAGE_CREATED, MESSAGE_SENT, etc.)
timestamp
Date/time event was created
subjectId
Identifier of a subject of the event
subjectType
Type of a subject of the event
data
Platform event serialized to JSON
The message component of Impel's ISO 20022 API
The message component is the primary object to house the financial message's data and optional digital asset information used for collateral that is passed from one gateway node to another gateway node, essentially getting the ISO 20022 financial message from point a to point b.
Impel's ISO 20022 API gateway service's message envelope utilizes cryptography, ensuring the following:
High throughput
Instant delivery
Guaranteed delivery
Secured delivery
A gateway service processes messages and proofs. Upon lifecycle state change, a new event message is generated. Clients retrieve events from the gateway service endpoint which is polled periodically by a Client:
GET /api/gateway/iso20022/gateway/event
Event Types are defined in API definition
MESSAGE_CREATED
Description: Triggered by a sender node when message is successfully created.
MESSAGE_SENT
Description: Triggered by a sender node when message is sent to a counterparty node.
MESSAGE_RECEIVED
Description: Triggered by a recipient node when a message is received and successfully created on a counterparty node.
MESSAGE_ACKNOWLEDGED
Description: Triggered by both (sender/recipient) nodes when a message is acknowledged by a counterparty node.
MESSAGE_NOT_ACKNOWLEDGED
Description: Triggered by both (sender/recipient) nodes when a message is not acknowledged by a counterparty node
PROOF_CREATED
Description: Triggered by a sender node when a proof is successfully created.
PROOF_SENT
Description: Triggered by a sender node when proof was sent to a counterparty.
PROOF_RECEIVED
Description: Triggered by a recipient node when a proof is received and successfully acknowledged by a counterparty node.
PROOF_ACKNOWLEDGED
Description: Triggered by both nodes when a proof is acknowledged by counterparty node.
PROOF_NOT_ACKNOWLEDGED
Description: Triggered by both nodes when a proof is not acknowledged by a counterparty node.
PROOF_COMMITTED
Description: Triggered by both nodes when a proof is successfully committed.
PROOF_APPROVED
Description: Triggered by both nodes when a proof is successfully approved.
PROOF_REJECTED
Description: Triggered by both nodes when a proof is rejected.
State | Description |
---|
NEW | Initial state of the message |
OUTBOX | Message is available to send to the counterparty |
SENT | Message has been sent to the counterparty |
RECEIVED | Message has been received by the counterparty |
ACKNOWLEDGED | Message has been checked and validated |
NOT_ACKNOWLEDGED | Message failed successful delivery |
The mechanics of Impel's ISO 20022 financial message
Impel's ISO 20022 API was designed to be message agnostic, meaning that it will house and send whatever data type the sender wants to send, MT or XML. The origination and fundamentals of the message that the client creates and sends to the gateway service that will be sent to the recipient that will be committed as a proof.
The data required to route message between gateways (sender, receiver).
SendMessageRequest data field requirements:
Sender
Recipient
Payload
Collateral (optional)
Validation
The AppHdr element is an ISO 20022 head message. Supported schemes:
head.001.001.01
head.001.001.02
head.001.001.03
AppHdr element:
The Document element is the actual ISO 20022 message e.g. PACS or PAIN.
The document schema attribute that points to the ISO 20022 schema type: urn:iso:std:iso:20022:tech:xsd:${MESSAGE_TYPE}
Example:
The ability to add a digital asset to the message's payload allows for instant settlement capability to where traditional nostro/vostro accounts and settling up at the end of the day with the Central Banking systems is no longer required.
Collateral is defined in SendMessageRequest by the optional collateral field.
Digital assets types supported:
NATIVE (XDC, the native coin to the XDC Network)
XRC-20 token (layer 2 projects)
Native XDC coin as collateral example:
XRC-20 token as collateral example:
All ISO 20022 message types and variants are candidates for validation. SendMessageRequest includes an optional flag "validatePayload" for validation.
ISO 20022 payload is validated by checking:
Document
AppHdr (optional)
Both elements has to be a valid ISO 20022 namespace, e.g.
urn:iso:std:iso:20022:tech:xsd:pain.002.001.03
urn:iso:std:iso:20022:tech:xsd:head.001.001.02
urn:iso:std:iso:20022:tech:xsd:pacs.002.001.12
Supplementary data is not supported by the platform.
Variable | Description |
---|---|
${HEADER_TYPE}
head.001.001.01 and head.001.001.02
${SENDER_BIC}
Sending party's BIC
${RECIPIENT_BIC}
Receiving party's BIC
${BUSINESS_IDENTIFIER}
Identification
${MESSAGE_TYPE}
pacs.009.001.10, pain.008.001.01, acmt.001.001.08, etc.
${MESSAGE_DATE}
Date the message was created
Detailed explanation of Impel's ISO 20022 API message confirmation
A Proof is a confirmation of a received message that has been validated, acknowledged (signed) by counter party, before it will be committed as a transaction on the XDC Network.
Messages received through the gateway service will be committed to the blockchain after successful proof validation via the following procedure:
Selects a batch of uncommitted messages
Creates a proof
Collects signatures
Commits proof
Approves/Rejects proof
Complete list of the ISO 20022 API's endpoints (methods)
An application programming interface is a way for two or more computer programs to communicate with each other. It is a type of software interface, offering a service to other pieces of software. A document or standard that describes how to build or use such a connection or interface is called an API specification. (as per Wikipedia)
The following API endpoints are located at this URL: https://api-sandbox.impel-lab577.co.uk/BBBBCAXXXXX/swagger-ui/index.html?configUrl=/BBBBCAXXXXX/v3/api-docs/swagger-config
Field | Description |
---|---|
Field
Description
ID
Message identifier
endToEndId
Message business identifier (extracted from ISO 20022 Business Application Header)
Status
Status of message (CREATED, SENT. etc.)
Direction
Message direction (INBOX, OUTBOX)
Sender
Message sender Party BIC (extracted from ISO 20022 Business Application Header)
Recipient
Message recipient Party BIC (extracted from ISO 20022 Business Application Header)
Signature
Sender Party signature for a message to send (base64 format)
counterpartySignature
Recipient Party signature for a received message (base64 format)
messageHash
Hash of a message (base64 format)
previousMessageHash
Hash of a previous message in a chain (base64 format)
Collateral
Information about message collateral
Type
Type of collateral, e.g NATIVE (XDC) or ERC20
Amount
Collateral amount
exchangePrice
Price of a collateral amount
exchangeCurrency
Currency of a collateral amount price
tokenSymbol
XRC-20 token symbol (e.g. US+)
messageIds
List of proof's messages platform identifiers
endToEndIds
List of proof's messages business identifiers
status
Status of a proof in the platform (CREATED, SENT...)
sender
Proof sender Party BIC
recipient
Proof recipient Party BIC
signature
Sender Party signature for a proof to send
counterpartySignature
Recipient Party signature for a received proof
channelHash
Hash of a proof's messages (hex format)
netSettlementCollaterals
Sum of proof's messages collaterals
Message id
Created
Ok
Ok
OK
The bank identification code (i.e. SWIFT/BIC)
Ok
Unique identifier for this party
Name of party
Swift BIC for this party
URL for this party's gateway
Base64 encoded certificate
Addresses for this party
XinFin address
The RSQL filter to apply as search criteria
The zero-indexed page number, optional
The page size, optional with default being 10
Ok
A filter to get events from given date
A filter to get events to given date
The zero-indexed page number
The page size
Ok
The RSQL filter to apply as search criteria
The zero-indexed page number, optional
The page size, optional with default being 10
Ok
Unique identifier for this party
Name of party
Swift BIC for this party
URL for this party's gateway
Base64 encoded certificate
Addresses for this party
XinFin address
Send message request
Message end to end id
Sender BIC
Recipient BIC
Message payload type
Message payload
Collateral
Collateral type, e.g. native XDC or ERC20 token
Collateral amount
Collateral exchange price
Collateral exchange currency
ERC20 token symbol, required when type is equal to ERC20
Flag which enables payload validation
Accepted
Message id
Message id
Ok
Proof status
Proof status change date time
Proof channel hash as hex
Sender BIC
Recipient BIC
Net settlement collaterals
Collateral type, e.g. native XDC or ERC20 token
Collateral net settlement amount
ERC20 token symbol
Flag which tells if all parties signed a proof
Initiator signature
Counterparty signature
Proof's messages identifiers
Proof's messages identifiers
Proof's messages end to end identifiers
Proof's messages end to end identifiers
Proof creation date time
Proof update date time
Message id
Flag if payload should be returned in a response
Ok
Message id
Message end to end id
Sender BIC
Recipient BIC
Message payload type
Message payload - returned only if requested
Collateral
Collateral type, e.g. native XDC or ERC20 token
Collateral amount
Collateral exchange price
Collateral exchange currency
ERC20 token symbol, required when type is equal to ERC20
Message status
Message direction (INBOX|OUTBOX) which tells if message was sent or received
Message hash
Previous message hash
Flag which tells if all parties signed a message
Initiator signature
Counterparty signature
Proof
Proof status
Proof status change date time
Proof channel hash as hex
Sender BIC
Recipient BIC
Net settlement collaterals
Collateral type, e.g. native XDC or ERC20 token
Collateral net settlement amount
ERC20 token symbol
Flag which tells if all parties signed a proof
Initiator signature
Counterparty signature
Proof's messages identifiers
Proof's messages identifiers
Proof's messages end to end identifiers
Proof's messages end to end identifiers
Proof creation date time
Proof update date time
Message creation date time
Message update date time
The RSQL filter to apply as search criteria
The zero-indexed page number, optional
The page size, optional with default being 10
The field to use for sorting
The sort direction, either ASC or DESC
Ok
Message id
Message end to end id
Sender BIC
Recipient BIC
Message payload type
Message payload - returned only if requested
Collateral
Collateral type, e.g. native XDC or ERC20 token
Collateral amount
Collateral exchange price
Collateral exchange currency
ERC20 token symbol, required when type is equal to ERC20
Message status
Message direction (INBOX|OUTBOX) which tells if message was sent or received
Message hash
Previous message hash
Flag which tells if all parties signed a message
Initiator signature
Counterparty signature
Proof
Proof status
Proof status change date time
Proof channel hash as hex
Sender BIC
Recipient BIC
Net settlement collaterals
Collateral type, e.g. native XDC or ERC20 token
Collateral net settlement amount
ERC20 token symbol
Flag which tells if all parties signed a proof
Initiator signature
Counterparty signature
Proof's messages identifiers
Proof's messages identifiers
Proof's messages end to end identifiers
Proof's messages end to end identifiers
Proof creation date time
Proof update date time
Message creation date time
Message update date time