From: Miro Metsänheimo Date: Sun, 13 Oct 2019 07:58:27 +0000 (+0300) Subject: Update readme and add conversion X-Git-Tag: v0.0.1~46 X-Git-Url: https://zoso.dev/?a=commitdiff_plain;h=0be3b587f6675b7577d28e86076228a18f2672e1;p=libnemo.git Update readme and add conversion --- diff --git a/README.md b/README.md index acd4888..aa873ab 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,173 @@ -# nanocurrency-web-js -Toolset for Nano cryptocurrency client side offline implementations +# nanocurrency-web +Toolkit for Nano cryptocurrency client side offline implementations allowing you to build web- and mobile applications using Nano without compromising the user's keys by sending them out of their own device. + +The toolkit supports creating and importing wallets and signing blocks on-device. Meaning that the user's keys should never be required to leave the device. + +## Features + +* Generate wallets with a BIP32 mnemonic phrase +* BIP39/44 private key derivation +* Mnemonic is compatible with the Ledger Nano implementation +* Import wallets with a mnemonic phrase or a seed +* Sign send, receive and change blocks with a private key +* Runs in all web browsers and mobile frameworks built with Javascript +* Convert Nano units + +--- + +## Usage + +``` +npm install nanocurrency-web +``` +| WARNING: do not use any of the keys or addresses listed below to send real assets | +| --- | +Wallet handling +``` +import { wallet } from 'nanocurrency-web' + +// Generates a new wallet with a mnemonic phrase, seed and an account +// You can also generate your own entropy for the mnemonic or set a seed password +// Notice, that losing the password will make the mnemonic phrase void +const wallet = wallet.generate(entropy?, password?) + +// Import a wallet with the mnemonic phrase +const wallet = wallet.fromMnemonic(mnemonic, seedPassword?) + +// Import a wallet with a seed +const wallet = wallet.fromSeed(seed) + +// Derive private keys for a seed, from and to are number indexes +const accounts = wallet.accounts(seed, from, to) +``` +``` +The returned wallet JSON format is as follows: +{ + mnemonic: 'edge defense waste choose enrich upon flee junk siren film clown finish luggage leader kid quick brick print evidence swap drill paddle truly occur', + seed: '0dc285fde768f7ff29b66ce7252d56ed92fe003b605907f7a4f683c3dc8586d34a914d3c71fc099bb38ee4a59e5b081a3497b7a323e90cc68f67b5837690310c', + accounts: [ + { + accountIndex: 0, + privateKey: '3be4fc2ef3f3b7374e6fc4fb6e7bb153f8a2998b3b3dab50853eabe128024143', + publicKey: '5b65b0e8173ee0802c2c3e6c9080d1a16b06de1176c938a924f58670904e82c4', + address: 'nano_1pu7p5n3ghq1i1p4rhmek41f5add1uh34xpb94nkbxe8g4a6x1p69emk8y1d' + } + ] +} +``` + +Signing a receive block +``` +import { block } from 'nanocurrency-web' + +const privateKey = '781186FB9EF17DB6E3D1056550D9FAE5D5BBADA6A6BC370E4CBB938B1DC71DA3'; +const data = { + // Your current balance in RAW + walletBalanceRaw: '18618869000000000000000000000000', + + // From the pending transaction + fromAddress: 'nano_1e5aqegc1jb7qe964u4adzmcezyo6o146zb8hm6dft8tkp79za3sxwjym5rx', + + // Your address + toAddress: 'nano_3kyb49tqpt39ekc49kbej51ecsjqnimnzw1swxz4boix4ctm93w517umuiw8', + + // From wallet info + representativeAddress: 'nano_1stofnrxuz3cai7ze75o174bpm7scwj9jn3nxsn8ntzg784jf1gzn1jjdkou', + + // From wallet info + frontier: '92BA74A7D6DC7557F3EDA95ADC6341D51AC777A0A6FF0688A5C492AB2B2CB40D', + + // From the pending transaction in RAW + amountRaw: '7000000000000000000000000000000', + + // Generate the work server-side or a DPOW service + work: 'c5cf86de24b24419', +} + +// Returns a correctly formatted and signed block ready to be sent to the blockchain +const signedBlock = block.sign(data, privateKey) +``` + +Signing a send block +``` +import { block } from 'nanocurrency-web' + +const privateKey = '781186FB9EF17DB6E3D1056550D9FAE5D5BBADA6A6BC370E4CBB938B1DC71DA3'; +const data = { + // Current balance from wallet info + walletBalanceRaw: '5618869000000000000000000000000', + + // Your wallet address + fromAddress: 'nano_1e5aqegc1jb7qe964u4adzmcezyo6o146zb8hm6dft8tkp79za3sxwjym5rx', + + // The address to send to + toAddress: 'nano_1q3hqecaw15cjt7thbtxu3pbzr1eihtzzpzxguoc37bj1wc5ffoh7w74gi6p', + + // From wallet info + representativeAddress: 'nano_1stofnrxuz3cai7ze75o174bpm7scwj9jn3nxsn8ntzg784jf1gzn1jjdkou', + + // Previous block, from wallet info + frontier: '92BA74A7D6DC7557F3EDA95ADC6341D51AC777A0A6FF0688A5C492AB2B2CB40D', + + // The amount to send in RAW + amountRaw: '2000000000000000000000000000000', + + // Generate work on server-side or a DPOW service + work: 'fbffed7c73b61367', +} + +// Returns a correctly formatted and signed block ready to be sent to the blockchain +const signedBlock = block.sign(data, privateKey) +``` + +Signing a change representative block +``` +import { block } from 'nanocurrency-web' + +const privateKey = '781186FB9EF17DB6E3D1056550D9FAE5D5BBADA6A6BC370E4CBB938B1DC71DA3'; +const data = { + // Your current balance, from account info + walletBalanceRaw: '3000000000000000000000000000000', + + // Your wallet address + address: 'nano_3igf8hd4sjshoibbbkeitmgkp1o6ug4xads43j6e4gqkj5xk5o83j8ja9php', + + // The new representative + representativeAddress: 'nano_1anrzcuwe64rwxzcco8dkhpyxpi8kd7zsjc1oeimpc3ppca4mrjtwnqposrs', + + // Previous block, from account info + frontier: '128106287002E595F479ACD615C818117FCB3860EC112670557A2467386249D4', + + // Generate work on the server side or a DPOW service + work: '0000000000000000', +} + +// Returns a correctly formatted and signed block ready to be sent to the blockchain +const signedBlock = block.sign(data, privateKey) +``` + +Converting units +``` +import { converter } from 'nanocurrency-web' + +// Convert 1 Nano to RAW +const converted = converter.convert('1', 'NANO', 'RAW') + +// Convert 1 RAW to Nano +const converted = converter.convert('1000000000000000000000000000000', 'RAW', 'NANO') +``` +--- + +## Contributions + +You are welcome to contribute to the module. To develop, use the following commands + +* `npm install` to install all the dependencies +* `npm run build` to build the Typescript code +* `npm run test` to run the tests + +## Donations + +If this helped you in your endeavours and you feel like supporting the developer, feel free to donate some Nano: + +`nano_35wfowmdqqe34uhmh4fo8i51kxkpr9ybahc4fb7yuzzxtez3oje4et5nk75d` \ No newline at end of file diff --git a/index.ts b/index.ts index 6178936..8133a47 100644 --- a/index.ts +++ b/index.ts @@ -1,6 +1,8 @@ import { AddressGenerator } from './lib/address-generator' import { AddressImporter, Account, Wallet } from './lib/address-importer' import BlockSigner, { TransactionBlock, RepresentativeBlock, SignedBlock } from './lib/block-signer' +import BigNumber from 'bignumber.js' +import NanoConverter from './lib/nano-converter' const generator = new AddressGenerator() const importer = new AddressImporter() @@ -136,7 +138,25 @@ const block = { } +const converter = { + + /** + * Convert Nano values + * + * Possible units are RAW, NANO, MRAI, KRAI, RAI + * + * @param {string | BigNumber} input The input value + * @param {string} inputUnit The unit of the input value + * @param {string} outputUnit The unit you wish to convert to + */ + convert: (input: string | BigNumber, inputUnit: string, outputUnit: string) => { + return NanoConverter.convert(input, inputUnit, outputUnit) + }, + +} + export { wallet, block, + converter, } diff --git a/test/test.js b/test/test.js index ef0f00b..ef769a6 100644 --- a/test/test.js +++ b/test/test.js @@ -1,7 +1,7 @@ 'use strict' const expect = require('chai').expect -const { wallet, block } = require('../dist/index') +const { wallet, block, converter } = require('../dist/index') // WARNING: Do not send any funds to the test vectors below describe('generate wallet test', () => { @@ -154,3 +154,17 @@ describe('block signing tests using official test vectors', () => { }) }) + +describe('unit conversion tests', () => { + + it('should convert nano to raw', () => { + const result = converter.convert('1', 'NANO', 'RAW') + expect(result).to.equal('1000000000000000000000000000000') + }) + + it('should convert raw to nano', () => { + const result = converter.convert('1000000000000000000000000000000', 'RAW', 'NANO') + expect(result).to.equal('1') + }) + +})