Skip to content

Latest commit

 

History

History
134 lines (90 loc) · 4.16 KB

README.md

File metadata and controls

134 lines (90 loc) · 4.16 KB
Raw

PCIDSS Compliant Oracle Gateway

PCIDSS Compliant Oracle contains set of services to process ISO-8583 services, sync with Substrate chain and maintain local ledger. In a nutshell, it mocks a traditional bank which has issued some cards and is currently used for implementing a PoC implementation of ISO-8583 on a Substrate based blockchain.

What it does?

Oracle service implements an RPC API for processing incoming ISO-8583 messages via MsgProcessor trait of iso_8583rs crate. In the future watcher service will be added, which will be used to subscribe to the Substrate chain for further integration of ISO-8583 standard.

How to run

Pre-requisites

  • Rust toolchain (tested with version 1.72.0)
  • Postgres database (tested with version 14.9)

OR

  • Docker and docker-compose

To run the oracle locally:

make run

# OR

RUST_LOG=info cargo run --release -p pcidss-oracle -- --dev

To build the binary for release and run it:

make build
# OR
cargo build --release


RUST_LOG=info ./target/release/pcidss-oracle

Docker and docker-compose

To start the oracle with the deployed Docker image and Postgres Docker container:

docker-compose up

If you want to build the Docker image locally, you will need to change Postgres settings to allow Docker container to connect to it (listened_addresses and trust authentication method).

To build the Docker image:

make docker-build
# OR
docker build --platform linux/x86_64 -t pcidss-oracle .

To run the Docker image:

make docker-run
# OR
# NOTE: your Postgres database should be accessible via host.docker.internal
docker run -p 0.0.0.0:3030:3030 --platform linux/x86_64 -it pcidss-oracle --database-host host.docker.internal --iso8583-spec /usr/bin/spec.yaml

CLI

Oracle service accepts the following arguments (which can be seen by running pcidss-oracle --help):

Usage: pcidss-oracle [OPTIONS]

Options:
      --database-host <DATABASE_HOST>
          Path to the Postgres database [default: localhost]
      --database-port <DATABASE_PORT>
          Port of the Postgres database [default: 5432]
      --database-user <DATABASE_USER>
          Username of the Postgres database [default: postgres]
      --database-name <DATABASE_NAME>
          Name of the Postgres database [default: postgres]
      --chain-endpoint <CHAIN_ENDPOINT>
          Substrate chain websocket endpoint [default: ws://localhost:9944]
      --iso8583-spec <ISO8583_SPEC>
          ISO-8583 specification file [default: spec.yaml]
      --rpc-port <RPC_PORT>
          RPC port [default: 3030]
      --dev
          Run in development mode (development accounts are injected)
  -h, --help
          Print help

NOTE: Make sure you pass your local postgres configuration in case it differs from the default values (e.g. pcidss-oracle --database-host localhost --database-port 5432 --database-user postgres --database-name postgres). Otherwise, you won't be able to run the oracle.

Testing

Oracle service has tests for the ISO-8583 message processing logic. You can run them with:

make test
# OR
cargo test --workspace --exclude oracle-e2e-tests

NOTE: Integration tests are run in parallel by default. This might cause issues with Postgres database, so we should run them in a single thread and one by one.

There is also a separate crate for testing end to end flow of the oracle service, however, it depends on the running Substrate client and Oracle, so it is not included in the main test suite.

cargo test -p oracle-e2e-tests

Linting and formatting

Oracle service uses rustfmt and clippy for formatting and linting. You can run them with:

make lint

Documentation

More on proposed architecture (and its comparison to traditional way of doing it):

implementation

And more about how it works:

Implementation plan

NOTE: Actual implementation might slightly differ from the presented solutions above.