DEMO.md

Demo for M2

For demonstration purposes, docker-compose configuration is provided. It will start the following services:

• Demo merchant application
• Payment Processor Server
• PCIDSS compliant oracle
• ISO-8583 compliant Substrate chain

To start the demo, first pull the images:

docker-compose pull

Then start the services:

docker-compose up

You will be able to access the demo merchant application at http://localhost:3002.

Insert the offchain worker key to substrate node:

curl -H "Content-Type: application/json" \
 --data '{ "jsonrpc":"2.0", "method":"author_insertKey", "params":["'"iso8"'", "'"news slush supreme milk chapter athlete soap sausage put clutch what kitten"'", "'"0xd2bf4b844dfefd6772a8843e669f943408966a977e3ae2af1dd78e0f55f4df67"'"],"id":1 }' \
"http://0.0.0.0:9944"

Then, you can access the explorer here.

NOTE:

• URL of the payment processor API is stored under ISO8583::PaymentProcessorUrl in the chain storage. It is set to http://sever:3001 by default, but you can change it to http://localhost:3001 if you are running the services locally (sudo wrapped setPaymentProcessorUrl extrinsic is provided for that purpose).
• To start from scratch, stop docker-compose and delete postgres-data folder. Then start the services again.
• If you want to add new bank accounts, add it to DEV_ACCOUNTS in pcidss/oracle/src/types.rs and restart the services (or just the oracle).

Milestone Goals

1. On-chain addresses can be associated with bank accounts
2. On-chain balance is synced with off-chain balance, off-chain ledger serves as a source of truth
3. It is possible to trigger ISO-8583 transactions (both payment and reversal) both from POS and on-chain transactions
4. On-chain messages are converted to ISO-8583 format and processed by the oracle
5. Oracles settle finalised ISO-8583 transactions on-chain

Demo flow

Demo of on-chain extrinsics and their interaction with the oracle gateway is documented here. This demo is aimed at showing the user facing side of the infrastracture, and in general the end product of all components.

Accounts and their roles

• Alice, Bob - oracle wallets, i.e used for submitting finality of ISO-8583 by PCIDSS oracles.
• Charlie, Dave, Demo User - wallets that are associated with corresponding bank account, come with balance and ready for using.
• Alice_stash, Bob_stash - wallets that will be used to demo associating on-chain accounts to bank account
• Eve - an account with expired card
• 5HRD6MDjy9XjX6gNhj7wSAinvpNw1DptfR73LZBz68zH4Gex - wallet associated with merchant's bank account, i.e it will receive payments from the checkout page.

Use these dev bank accounts for testing payment and reversal. Note that the Demo User account has a private key, which you have to add to Polkadot.js extension if you want to use it to sign transactions.

[
    {
        "name": "Charlie",
        "card_number": "4169812345678903",
        "expiration_date": "03/28",
        "cvv": "125"
    },
    {
        "name": "Dave",
        "card_number": "4169812345678904",
        "expiration_date": "03/28",
        "cvv": "126"
    },    
    {
        "name": "Demo User",
        "card_number": "4169812345678900",
        "expiration_date": "03/28",
        "cvv": "123",
        "private_key": "intact start solar kind young network dizzy churn crisp custom fuel fabric"
    }
]

Use these predefined dev bank accounts for testing. They are not associated with any on-chain account.

[
  {
    "name": "Alice_stash",
    "card_number": "4169812345678908",
    "expiration_date": "03/28",
    "cvv": "999"
  },
  {
    "name": "Bob_stash",
    "card_number": "4169812345678909",
    "expiration_date": "03/28",
    "cvv": "888"
  }
]

NOTE: expiration date is always 4 years away from current time, i.e 03/2028 assuming we are in 03/2024.

Now, everything is ready for the demo.

On-chain address association

By opening the demo merchant application, you will see the simulation of a bank dashboard, where you can see basic details about the bank account and its transactions. To ease the testing, there is a button on the top right corner that allows you to switch between wallets. You can use development accounts to simulate different scenarios.

When an address you switched to is not associated with any bank account, you will be redirected to the registration page, which will ask for your card details. After submitting the form with one of the predefined bank account details from above, you will be redirected back to the dashboard. Registration request is ISO-8583 message, which is processed and settled on chain by the oracle.

On-chain association:

On-chain balance synchronization

If you check for account balances from the explorer, you will see that they match what is shown on the dashboard. And offchain worker periodically (every 10 blocks) runs and updates the latest balance of accounts from the bank backend.

ISO-8583 transactions

Payment

Now, to actually see how on-chain balance is synced and how ISO-8583 transactions are processed, we can use the checkout page. It is a simple form that asks for card details in a checkout session, i.e when paying for some goods. It is a simulation of a POS terminal, part of delivery of Milestone 1. Submit the form with any of the dev bank account details, here we will use Charlie:

It will forward us back to the Dashboard where we can see that the balance has been decreased and off-chain ledger transaction is recorded.

By checking the explorer, you will notice that offchain worker detects change in the balance and updates on-chain balance after couple of blocks (10 blocks ~30s currently). This is not a limitation of the system, because the source of truth is always off-chain ledger.

With Milestone 2, we added the ability to trigger ISO-8583 transactions with on-chain transaction. To do that, you have to switch to Crypto tab and click on Pay button. It will trigger an extrinsic which you have to sign and submit (if you are using development accounts it will not prompt signature, i.e Alice, Charlie, etc.)

Make sure you have selected a proper wallet, in the screenshot above it is Dave.

Reversal

Reversal can be triggered in the dashboard, similar to how it was after the Milestone 1.

Note that this is an off-chain ledger transaction and it can only be reversed once.

For triggering reversal using Polkadot.js, take a look at the Demo of ISO-8583 chain

Settlement

Note that in the explorer, you will initially see InitiateTransfer event, and after couple of blocks ProcessedTransaction event. This is because of event driven nature of current implementation. Most of the times, however, transaction is initiated and processed in the next or 2 blocks later. Since we are using off-chain ledger as a source of truth, on-chain settlement's speed is not really important, however it is important for UX since wallets need to be notified when transaction is settled (i.e by tracking ProcessedTransaction event).

Transfers between wallets

For transferring between wallets, please refer to the Demo of ISO-8583 chain