Offline mass transfer

Process of preparing a mass transfer offline using a command line tool.

Introduction

The purpose of this process is to sign and distribute a large number of transfers in a secure way without consuming the Minka API or implementing the SDK on the originator side.

All the movements of balances in the Minka Cloud are initiated by messages derived from private keys that are generated at the source. The management of the keys is the responsibility of the source and it is recommended to prepare the mass-transfers offline if you are not using the API interface.

Since all transfers are signed using asymmetric cryptography the signed transfers could be sent using any channel.

The tool also provides a secure way to submit the transfers to protect the information in transit and requires a user login.

Setting up the tool

Introduction

A command line tool is provided to prepare the batch file and the signature. The tool is an npm package and a npm is a package manager for the JavaScript programming language is a prerequisite to execute the tool. About npm:

https://docs.npmjs.com/downloading-and-installing-node-js-and-npm

Install the package

First step is to install the mass-transfer package on the local computer or server that can be found on https://www.npmjs.com/package/@minka/mass-transfer

$ npm install -g @minka/mass-transfer

Initializing the tool

Generate the initial template files with mass-transfer init

$ mass-transfer init

Successfully generated files:
 * keys.json
 * mass-transfer.csv
 * transfer.js

Creating the mass-transfer file templates does not require a login.

Login to remote server

Mass transfer service is a remote server provided by Minka where the file will be uploaded.

You can login to the service using email and password. This command performs a login request and saves a returned token locally in the current directory.

$ mass-transfer login [e-mail]
? Password: [hidden]

Logged in as [e-mail], your session expires in an hour.

File structure

Transfers

mass-transfer.csv is a file that contains information about transfers that need to be executed. This is a standard CSV file with columns defined on the first line, the file can contain any number of columns which can be used in order to construct transfers, for example:

• Source is the wallet or signer handle

• Target represents wallet or signer handle

• Amount represents the amount (decimal point)

source,target,amount
wNHUK4M9VdHrALYMbSytAWPBXFonGSiJev,$573002414263,10000.00
wNHUK4M9VdHrALYMbSytAWPBXFonGSiJev,$573002414264,10000.00
wNHUK4M9VdHrALYMbSytAWPBXFonGSiJev,$573002414265,30000.00
wNHUK4M9VdHrALYMbSytAWPBXFonGSiJev,$573002414266,10000.00

Template for metadata

transfer.js serves as a template for building transfers, it allows using any column from the mass-transfer.csv file in order to generate a new transfer object. The configuration is a js file so it gives a the flexibility to use the full power of JavaScript, in case the transfers needs to implement some more advanced logic:

module.exports = csvData => ({
  source: csvData.source,
  target: csvData.target,
  amount: csvData.amount,
  symbol: '$tin',
  labels: {
    description: 'Transaction description',
    domain: 'tin',
    type: 'PAYOUT',
    sourceChannel: 'MassTransferCLI'
  }
})

The originator can use the standard template file to create transfers, no modification or development is necessary for standard payouts or requests.

Keeper - private keys configuration

keys.json is a file that should contain the keys used to sign transfers. Those keys should be setup in advance and added to the file before signing transfers.

In the file, addresses are mapped to keys for those signers (address) :

{
  "wNHUK4M9VdHrALYMbSytAWPBXFonGSiJev": 
  {
    "scheme": "ed25519",
    "public": "041d8bf211ab07e1b66f82090fde3815bddd4ae8b8d313db5788c0990f58a8b8d65a33737c02c547de3e03d8624833a62042e9ef178ffbc84c821a457c3119603b",
    "secret": "0a57b7bad498a251cbb47b369e5eed70dc1fdb039d0370fce624406240a84466"
  }
}

Secret or private key is critical data that should handled with care. Private keys are used to modify balances and should not be shared to the Minka Cloud or any intermediary in the process.

Executing the transfer

Signing the transfers

After everything is in place, a client needs to sign all transfers in the batch with the sign command

$ mass-transfer sign mass-transfer.csv
Successfully created signed transfers!
Output file: mass-transfer-signed.csv (8.14 MB)

This command will create a new CSV file (mass-transfer-signed.csv) that will have an additional column called transfer in each row with a signed transfer built from the data of that row:

source,target,amount,transfer
wNHUK4M9VdHrALYMbSytAWPBXFonGSiJev,$573002414263,10000.00,"{ ""source"": ""wNHUK4M9VdHrALYMbSytAWPBXFonGSiJev"", ""target"": ""$573002414263"", ""amount"": 10000.00, ""symbol"": ""$tin"", ""labels"": { ""description"": ""Transaction description"", ""domain"": ""tin"", ""type"": ""SEND"", ""sourceChannel"": ""MassTransferCLI"", ""transferSignature"": ""<signature>"" }}"
wNHUK4M9VdHrALYMbSytAWPBXFonGSiJev,$573002414264,30000.00,"{ ""source"": ""wNHUK4M9VdHrALYMbSytAWPBXFonGSiJev"", ""target"": ""$573002414264"", ""amount"": 30000.00, ""symbol"": ""$tin"", ""labels"": { ""description"": ""Transaction description"", ""domain"": ""tin"", ""type"": ""SEND"", ""sourceChannel"": ""MassTransferCLI"", ""transferSignature"": ""<signature>"" }}"
wNHUK4M9VdHrALYMbSytAWPBXFonGSiJev,$573002414265,10000.00,"{ ""source"": ""wNHUK4M9VdHrALYMbSytAWPBXFonGSiJev"", ""target"": ""$573002414265"", ""amount"": 10000.00, ""symbol"": ""$tin"", ""labels"": { ""description"": ""Transaction description"", ""domain"": ""tin"", ""type"": ""SEND"", ""sourceChannel"": ""MassTransferCLI"", ""transferSignature"": ""<signature>"" }}"
wNHUK4M9VdHrALYMbSytAWPBXFonGSiJev,$573002414266,10000.00,"{ ""source"": ""wNHUK4M9VdHrALYMbSytAWPBXFonGSiJev"", ""target"": ""$573002414266"", ""amount"": 10000.00, ""symbol"": ""$tin"", ""labels"": { ""description"": ""Transaction description"", ""domain"": ""tin"", ""type"": ""SEND"", ""sourceChannel"": ""MassTransferCLI"", ""transferSignature"": ""<signature>"" }}"

Submit the file

The last step is to submit this file for processing using the submit command

$ mass-transfer submit mass-transfer-signed.csv
? Submit mass-transfer.csv for processing? Yes

Mass transfer submitted successfully, id: 39dm3udde3

Submitting a mass transfer is the first operation that needs to interact with a remote server. Before this call we make sure that you have logged in to the remote server

Get status of a mass transfer

The tool also supports getting statuses of submitted transfers. To get a status summary of a mass transfer use the mass-transfer status command with the id of a submitted mass transfer:

$ mass-transfer status 39dm3udde3
Mass transfer status summary:
COMPLETED: 3
PENDING: 1
ERROR: 1

Request or send transfers are async operations and the status of each transfer depends on the successful completion of the operations on the target side.

Get a report file from the Cloud

A detailed report is also available by using mass-transfer report command. This commands retrieves a status of each transfer from the original CSV file and returns a similar file that includes a status of each submitted transfer.

$ mass-transfer report 39dm3udde3
Retrieving report for mass transfer 39dm3udde3...
Report saved as report-39dm3udde3.csv