Skip to content

Introduction

Author: blacktyg3r | BT Labs

The Epic-Cash project is using the Mimblewimble protocol which is still a relatively new technology. Interactive transactions are not easy to implement in the production, and documentation is still developing. Our Blockchain privacy features will bring more challenges than other projects with transparent and public ledgers that are easy to query to get i.e. balances or transaction history by anyone.

This document aims to help developers with the integration process, and should be considered only us guidance. To fully understand concepts and terminology it is recommended to read other sections of the EPIC Developers Documentation and Epic-Cash Wiki on GitHub.

Interactive Transactions

The Epic-Cash Blockchain does not store any transaction data on the ledger, it uses Interactive Transactions (NIT), that means exchanging transaction slates1 requires all the participants to sign the transaction before posting it to the network. Sender can not finish the transaction without the recipient signature, and this introduces need of both wallets being online at some point during the process.

1. Transaction slate - partial transaction data (i.e. participants details, amounts, used outputs, etc.) that is not complete yet.

Overview

SRS vs RSR Workflow

Transaction can be initialized by both, the sender or the receiver, this gives us two different workflows:

  • Sender-Receiver-Sender when transaction is initialized by sender
  • Receiver-Sender-Receiver when transaction is initialized by the recipient (like issuing an invoice)

Wallet that initializes the transaction (1st step) is also responsible for finalization and posting it to the network (3rd step).

While SRS workflow will be the best choice for most cases, RSR can be used i.e. in e-commerce (asking client to pay for the product or service).

Despite different transaction methods that may change the user's experience, wallet's back-end will always have to use these functions (also available as API endpoints):

SRS Workflow:

  1. init_send_tx Used by the sender's wallet to initialize the transaction slate.
  2. receive_txs Used by the receiver's wallet to process initialized transaction slate, produces response slate.
  3. finalize_tx Used by the sender's wallet to finalize the transaction signed by the recipient.
  4. post_tx Used by the sender's wallet to post final transaction slate to the network.

and

RSR Workflow:

  1. issue_invoice_tx Used by the receiver's wallet to initialize new invoice payment.
  2. process_invoice_tx Used by the sender's wallet to processes an invoice transaction created by the recipient.
  3. finalize_invoice_tx Used by the receiver's wallet to finalizes an invoice transaction signed by the payer.
  4. post_tx Used by the receiver's wallet to post final transaction slate to the network.

Warning

At the moment of writing this document this workflow is considered as experimental and not tested in the production, use with caution.

After successful executing of the post_tx function coins are sent to the recipient, until then transaction can be canceled by both wallets. Transaction is considered as finished if and only if status confirmed in the wallet local database have value True.

Coins are safu, always!

One of the big advantages of the NIT's implementation is no risk of losing funds due to mistyped wallet address or connection problems, transaction either appears in the right wallet or nothing happens.

Transaction Slates

To exchange the EPIC coins, users must exchange transaction slates in one form or another. A transaction slate is a blob containing the necessary data to be included at each step of the transaction building process. Different transaction methods are basically different methods of exchanging slates to improve the end-user's experience.

Explaining Transaction Slates

Imagine you want to give someone a collection of two precious gold coins. In order to make that transaction legit for the accounting purposes, you document some details, such as:

Date: 
Participiants:
    - Sender    : 
    - Recipient : 
Products:
    - 
    -
Description: 
Signatures:
    - Sender    : 
    - Recipient :
    - Accountant :
  • So here, we enter the specific details, such as:
Date: "2023-04-26"
Participiants:
    - Sender    : "John Doe"
    - Recipient : 
Products:
    - "Coin 1"
    - "Coin 2"
Description: "Gold coins, perfect condition."
Signatures:
    - Sender      : "<John's Signature>"
    - Recipient   :
    - Accountant :
  • Now it's time to send the document to the receiver, let's use a delivery company, with an extra service to ensure your document is properly secured. Once it will be delivered and processed by the receiver it may look like this:
Date: "2023-04-26"
Participiants:
    - Sender    : "John Doe"
    - Recipient : "Steven Clark"
Products:
    - "Coin 1"
    - "Coin 2"
Description: "Gold coins, perfect condition."
Signatures:
    - Sender      : "<John's Signature>"
    - Recipient   : "<Steve's Signature>"
    - Accountant :
  • Now, using the same delivery service, the sender-signed document is returned to you. When it arrives, there is an authorized accountant with you to prove the authenticity of the coins, approve the document parameters and put the final signature on it:
Date: "2023-04-26"
Participiants:
    - Sender    : "John Doe"
    - Recipient : "Steven Clark"
Products:
    - "Coin 1"
    - "Coin 2"
Description: "Gold coins, perfect condition."
Signatures:
    - Sender      : "<John's Signature>"
    - Recipient   : "<Steve's Signature>"
    - Accountant : "<Accountant's Signature>"
  • The process is finished, the document is now a valid proof of ownership of the coins!

Doesn't sound that complicated, right? Now, let's translate that example to the Mimblewimble language:

  • Transaction slate is like the document we exchange with the receiver,
  • JSON payload is like content of that document, each round adds more details,
  • Transaction method (i.e. HTTP/S, Epicbox, etc.) is like the delivery company,
  • Data encryption is this special delivery service protecting your parcel,
  • The Mimblewimble protocol, same as the authorized accountant, validates the entire process


The three rounds mentioned above are related to the order of the functions used by the wallet:

Public vs Private

Now that we know how it works using a transparent and public ledger, let's outline the key differences when compared to the secure and private EPIC Blockchain:

  • Participiant's data is not linkable, nor trackable, no addresses or meta-data are stored,
  • Transaction details are encrypted (sealed), and no one except the participating wallets can look inside,
  • Signatures are secured by cryptographic functions, not possible to cheat,
  • Blockchain keeps the data needed to prove ownership of the coins, but does not say (or know) who actually owns them, there is no way to query asset balances

Wallet Addresses

In the Mimblewimble protocol there is no wallet addresses!

With that being said, we do need them in order to make transactions available for the users.

HTTP/S Addresses

What is not present on the protocol level was built on top of it - this is how HTTP/S Transaction method was created, where wallet address is an IP (or domain) of the machine where wallet is running. While for private users this immediately raises a privacy concerns (sharing the IP address), for commercial use is actually a great solution. How exactly HTTP/S Transaction method works will be explained later, for now let's outline key points:

Pros

  • Highly customizable URL links working as wallet address
  • Having own custom domain URL to keep brand consistency, i.e. ExampleShop.com/pay as payment address
  • Static and user-friendly addresses instead of long and ugly strings
  • Multiple different URLs pointing to the same wallet
  • Peer2Peer connection between wallets, no intermediate service

Cons

  • Configuration requires some tech experience
  • Hosting machine must be reachable for network traffic, i.e. open ports and firewall rules
  • Sender's and receiver's wallet must be running in the same time in order to transact
  • Connection problems may result with need to re-send the transactions

It is clear that this type of addresses are great match for commercial cases like exchange deposits, e-commerce payments, branding, etc. Unfortunately in the same time it is complicated for standard users without tech experience - this is why we had to introduce something more user-friendly.

Epicbox Addresses

Epicbox is not just an address, it is completely new transaction workflow with multiple benefits focused primarily on creating smooth experience for the end-users. Stealth-like, not queryable and static wallet addresses used to exchange transaction slates with similar to other cryptocurrency projects fashion:

Pros

  • Highly private and secure with almost no meta-data leak during the transaction process
  • No extra configuration or tech experience needed, working out of the box
  • No need for both wallets to be online at the same time
  • Mobile wallet friendly

Cons

  • Not customizable and not as user-friendly as HTTP/S addresses
  • Requires intermediate service to store pending transactions

It seems like the biggest tradeoff in this case is the requirement of intermediate service handling communication between the wallets, but why this should not raise any concerns will be explained in the next sections.

TOR Addresses

For those who value privacy we have also integrated anonymous communication between the wallets over TOR routing protocol.

Using TOR

Taking into consideration legal problems with using TOR it is very unlikely for someone to use this workflow in production for now (it is planned to eventually update that section though).

Transaction Methods

EPIC Wallet supports multiple (five at the moment) transaction methods. Let's briefly look at all of them:


HTTP/S

To use this method receiver have to run HTTP/S Listener, share the URL address (IP or domain) pointing to it and make sure it is reachable for others outside the LAN network, i.e. port (by default 3415) is open and firewall rule created.

Transaction will be successfully finished if and only if both parties are online during the entire process which should take no longer than few seconds. Failed transaction can be cancelled by sender to unlock locked funds.

Epicbox

To use this method both sender and receiver have to run Epicbox listener.

Epicbox server will work as temporary storage to make it possible to transact without the need of both parties being online at the same time. It will also remove the need of sharing receivers IP address and handling the ports.

TOR

To use this method receiver have to run HTTP/S Listener and share the TOR address.

Transaction will be successfully finished if and only if both parties are online during the process which should take less than a minute. Failed transaction can be cancelled by sender to unlock locked funds.

Transaction Files

This method requires to do all 3 steps manually giving the user a lot of flexibility how to do it, i.e. via e-mail, messengers, USB drives, Bluetooth, etc. Transaction slates are saved as text files, users have to exchange them between each other until all the details are completed and final file is ready to post to the network.

Emojis Strings

Very similar to the transaction files method except in this case instead of files we use emojis strings.

Example Emojis Transaction Slate

🥉🎨📏🤛🪞🥼💸🤎🚟🧞📷😶🪒🈶🍚 [....] 🦨📵📭😡🦦🤞🐉🦷🦏 🐪💾