Comment on page
Offline mass transfer
Process of preparing a mass transfer offline using a command line tool.
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.
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
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
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.
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 [email protected]
? Password: [hidden]
Logged in as [email protected], your session expires in an hour.
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
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.
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.
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>"" }}"
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
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.
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
Last modified 3yr ago