Update readme and add conversion

diff --git a/README.md b/README.md
index acd4888a8d1409c624ddd4fa35a588e1b0d9ae45..aa873ab9213c4f333dd90581d350e4256f287313 100644 (file)
--- 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 61789366d688628d4a98011036419928b6525b8b..8133a472d0848ea46e3c591bb6ac6b4627306f73 100644 (file)
--- 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 ef0f00bdb79c222a34ecef43deb6f75d7c2b02da..ef769a6c6d00059ac9a38ded6d0a43b27e0ee78e 100644 (file)
--- 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')
+       })
+
+})