@minka/mass-transfer

Offline mass transfer

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

Introduction

The purpose of this tool is to sign and distribute 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. Credentials should be obtained directly from Minka.

Setting up the tool

Install the package

First step is to install the mass-transfer package on the local computer or server:

$ 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

Template files

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,$573002414264,10000.00
wNHUK4M9VdHrALYMbSytAWPBXFonGSiJev,$573002414265,30000.00
wNHUK4M9VdHrALYMbSytAWPBXFonGSiJev,$573002414266,10000.00
wNHUK4M9VdHrALYMbSytAWPBXFonGSiJev,$573002414267,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 it is necessary to implement some more advanced logic when building transfers:

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

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

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.

The file contains a mapping from addresses to keys:

{
  "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 file 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>"" }}"

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.

Only submitting files for processing requires login. Credentials should be obtained directly from Minka.

Submit the file for processing

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

$ mass-transfer submit mass-transfer.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.