search

mojaloop / design-authority-project

This is the Issue and Decision Log for tracking mojaloop and related Designs
Other
1 stars 2 forks source link

Review Original Mojaloop Project Principles #70

Closed godfreykutumela closed 3 months ago

godfreykutumela commented 4 years ago

One Line Summary:

The design and development of Mojaloop was based on a set of principles which were never properly documented and communicated and as part of this initiative, the DA will review the provided list of principles from the TGB and provide feedback before releasing to the open community for only additions and corrections no detailed review is needed.

Request Details:

The TGB seeks to ensure that the project principles are known and adhered to by the broader community starting with the DA and to this effect, the DA will take a first step in reviewing the principles and handshake feedback with the TBG and therefore the principles will be broadly communicated to the community. Below is a summary of the principles :

Core Principles:

• Clear in real-time, settle by end of day • Full automatic pass-through processing • No manual reconciliation — protocol guarantees determinism automatically • No repudiation of transactions by facilitators • Separate the transaction logic and use cases from the policy-free transfer of money • Hub doesn’t parse or act on transaction details • Simplify money transfer semantics and standardize them • Internet-based API service hub is not a “message switch” • Asynchronous processing to optimize responsiveness and throughput • Hub may serve as proxy to simplify interconnection, without parsing or storing messages. Performance Targets

• Baseline deployed system supports 1,000 FTPS, sustained for one hour, with not more than 1% of transfers exceeding 1 sec through the hub. And lower unit cost to scale than to initially provision. • Use nodejs microservices architecture • Implement a hash time lock of transactions details using the Interledger Protocol in Universal Mode

Artifacts:

Dependencies:

Accountability:

Decision(s):

Outstanding

Details

Follow-up:

godfreykutumela commented 3 years ago

https://docs.google.com/document/d/1OwO3W4IOIsDURqQsOFP1DKN6hrAt2otKd0VRSNxBEWY/edit?ts=5ff4465d

MichaelJBRichards commented 1 year ago

This is the invariants question. Leave open.

millerabel commented 1 year ago

Mojaloop Invariants

The following invariants have been established during the course of the platform’s development and based upon the technical requirements inferred from the Level One Project Principles (※a) These invariants should guide any product and technical design discussions related to the architecture of the platform.

  1. The primary (※d) function of the platform is to clear payments in real-time and facilitate regular settlement, by the end of the value day.
    1. The platform allows participants to clear funds immediately to their customers while keeping the risks and costs associated with this to a minimum
    2. The platform supports per-transfer checks on available liquidity where these are required in support of the first objective
    3. The system is optimized for critical path
    4. Intra-day Automated Settlement—configured by scheme and implementation using recommended settlement models for financial market infrastructure
  2. The system supports fully automatic straight-through processing.
    1. More information here: [https://www.investopedia.com/terms/s/straightthroughprocessing.asp]()
  3. The system requires no manual reconciliation as the protocol for interacting with the system guarantees deterministic (※g) outcomes.
    1. When a transfer is finalized, there can be no doubt about the status of that transfer (alternatively, it is not finalized and active notice provided to participants)
    2. The system guarantees deterministic outcomes for transfers and is accepted by all participants as the final authority on the status of transfers
    3. Determinism means individual transfers are traceable, auditable (based on limits, constraints), with final result provided within guaranteed time limit
    4. For the avoidance of doubt, batch transfers are processed line-by-line with potentially differing deterministic outcomes for each
  4. Transaction setup logic, which is use case-specific, is separated from the policy-free transfer of money.
    1. Transaction details and business rules should be captured and applied between counterparties prior to the quoting phase and is out of scope for Mojaloop.
    2. The agreement phase establishes a signed use-case specific transaction object which incorporates all transaction-specific details.
    3. The transfer phase orchestrates the transfer of retail value between institutions for the benefit of the counterparties (i.e only system limit checks are applied) and without reference to transaction details.
    4. No additional transaction-specific processing during the transfer phase.
  5. The system doesn’t parse or act on end-to-end transaction details; transfer messages contain only the values required to complete clearing and settlement.
    1. Checks & validations during the transfer step are only for conformance to scheme rules, limit checks, signature authentication, and validation of payment condition and fulfillment.
    2. Transfers that are committed for settlement are final and are guaranteed to settle under the scheme rules.
  6. Credit-push transfer semantics are reduced to their simplest form and standardized for all transaction types.
  7. Internet-based API service hub is not a “message switch.”
    1. The service hub provides real-time API services for participants to support retail credit-push instant transfers
      1. API services such as ID-to-participant look-up, transaction agreement between participants, submission of prepared transfers, and submission of fulfillment advice.
    2. Auxiliary API services for participants are provided to support onboarding, position management, reporting for reconciliation, and other non-realtime functions not associated with transfer processing.
    3. All messages are validated for conformance to the API specification; non-conforming messages are actively rejected with a standardized machine-interpretable reason code.
  8. The system exposes asynchronous interfaces
    1. To maximize system throughput
    2. To isolate leaf-node connectivity issues so they don't impact other end-users
    3. To enable the hub system to process requests in its own priority order and without holding an active connection-per-transfer
    4. To handle numerous concurrent long-running processes through internal batching and load balancing
    5. To have a single mechanism for handling requests (Examples are transactions such as bulk or those needing end user input or that span multiple hops).
    6. To better support real world networking as issues with connection speed and reliability for one participant should have minimal impact on other participants or system availability more generally
  9. The transfer API is idempotent ensuring duplicate requests are recognized and result in the same outcome (valid duplicates) or are rejected as duplicate (when not allowed by specification) with reference to original
  10. Finalized Transfer records are held for a scheme-configurable period to support scheme processes such as reconciliation, billing, and for forensic purposes
    1. It is not possible to query the "sub-status" of an in-process Transfer; the API provides a deterministic outcome with active notice provided within the guaranteed service time
  11. Transfer records for finalized transfers are held indefinitely in long-term storage to support business analysis by the scheme operator and by participants (through appropriate interfaces)
    1. Availability of Transfer records may lag online process finality to accommodate separation of record-keeping from real-time processing of Transfer requests
  12. Hub may serve as a proxy for some inter-participant messages (e.g. during the Agreement phase) to simplify interconnection but without parsing, storing (other than to support forwarding), or further processing the messages.
  13. Security (※j) and Safety of APIs
    1. API messages are confidential, tamper-evident, and non-repudiable.
    2. API messages are Authenticated upon receipt prior to acceptance or further processing
    3. Authenticated Messages are not acknowledged as accepted until safely recorded to permanent store.
  14. Three levels of communication security to ensure integrity, confidentiality, and non-repudiation of messages between an API server and API client.
    1. Secure Connections: mTLS required for all communications between the scheme and authorized participants.
      1. Ensures communications are confidential, between known correspondents, and communications are protected against tampering.
    2. Secure Messages: JSON message content is cryptographically signed according to the JWS specification.
      1. Ensures recipients that messages were sent by the party which purported to send them and that provenance can not be repudiated by the sender.
    3. Secure Terms of Transfer: Interledger Protocol (ILP) between Payer and Payee participants.
      1. Protects the integrity of the payment condition and its fulfillment.
      2. Limits the time within which a transfer instruction is valid.
  15. To ensure system is arithmetically consistent, only fixed point arithmetic is used.
    1. For the avoidance of doubt, floating point calculations may lose accuracy and must not be used in any financial calculation
    2. See Level One Decimal Type representation and forms
      1. This specification enables seamless interchange with XML-based financial systems without loss of precision or accuracy
  16. Performance Requirements
    1. Baseline system demonstrated on minimal hardware supports 1,000 FTPS, sustained for one hour, with not more than 1% of transfers exceeding 1 sec through the hub.
    2. Lower unit cost to scale than to initially provision.

Design Decisions

  1. NodeJS is the primary execution environment with TypeScript the preferred language for development.
    1. This platform is free open source
    2. Is widely used and actively supported by the world's largest web-based institutions
    3. Has a massive global portfolio of libraries
    4. Utilizes only the ECMAScript family of architecture-neutral languages and libraries known by millions of skilled web programmers
  2. Use a micro-service distributed architecture.
    1. Law of Demeter or Principle of Least Knowledge
    2. Separation of concerns secured by inter-module contracts
    3. Modular architecture enables distributed development in a community environment and improvement of components with minimal disruption to adjacent components
  3. Apache Kafka distributed Publish–Subscribe for inter-module Command–Query Separation (CQS)
  4. Apache Kafka for persistent handling of participant API messages
  5. Mojaloop uses APIs based on Open API 3.0
    1. Exposes resources that are mapped to functionality to support the defined API use-cases.
    2. Common practice for web API specification

Annexure A : Level One Principles Overview

The Level One Project proposes a new low-cost payments system that supports inclusive, interoperable digital payments. The Level One Project Guide outlines a vision of how an inclusive digital financial services system can work for the benefit of poor people. The underlying design principles of the Guide include:

By utilizing an open, digital approach to transactions, and partnering with organizations across the public and private sectors, the Level One Project aims to provide access to a robust, low-cost shared digital financial services infrastructure, sparking innovation from new and existing participants, reducing risk, and generating substantial value for providers, individuals and economies in developing markets. Additional resources have been created to help governments, NGOs and financial service providers successfully implement these changes.

Editorial Notes

※a

If we don't capture the rationale, the reason why these principles are important, future generations of Mojaloopers will not understand the context that drove the selection of the principles and might happily discard without appreciating the potential impact.

Noted — we will re-open this and provide additional context as suggested.

agreed - that was the intention of the comments I gave (which I am not sure were fully answered with the responses/changes - there wasn't enough of the why to make it sufficiently useful to outsiders.

great that we're re-opening. and happy to review again through a product lens (as fundamentally some of these should form the core of our messaging/positioning to adopters)

※d

Would add to be the authoritative system of accounting record

covered in #3, is that sufficient?

no, it's a primary function

※g

Non-repudiabile? We need to tie back to some of the high level principles

Covered in #10 - security

not actually covered in #10 - and needs to be understood in the context of deterministic behaviour

※j

need to explain why necessary to achieve non-repudiation

Added additional description text around general confidentiality, integrity and non-repudiation

Agreed, this is about high throughput concurrency and accuracy not pure speed and latency. And the constraint should be recorded somewhere - it goes something like this- the switch would never allow a participant to exceed their position cap on the collateral made available to the system

The records need to explain the deterministic manner any decisions were arrived and have the accounting records that show both successful, declined transfer request and errors

Necessary for complete record and dispute Management

millerabel commented 1 year ago

Converted the Invariants to a draft in Markdown format. I've captured the inline comments, but they should be reviewed and deleted after we've processed them. This document should now be placed under version control in the appropriate repo where we can party on it with full Git.

millerabel commented 1 year ago

@bushjames @elnyry-sam-k @PaulMakinMojaloop — Let's progress this...

bushjames commented 1 year ago

Many thanks for this @millerabel .

bushjames commented 10 months ago

Please see PR against the mojaloop documentation repository adding the invariants to technical docs: https://github.com/mojaloop/documentation/pull/428

bushjames commented 8 months ago

All community members wishing to commend on the PR before it is merged should do so immediately. Note that there are additions and updates that should be carefully reviewed by interested parties. The DA will be asked to vote to accept the contents of the PR as the Mojaloop Invariants.

elnyry-sam-k commented 8 months ago

Approved from my side. Thanks James.

bushjames commented 3 months ago

Invariants published publicly after rounds of DA review here: https://docs.mojaloop.io/community/standards/invariants.html

Closing as done.