Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/numsu/nanocurrency-web-js

Toolkit for Nano cryptocurrency client side offline integrations without requiring NodeJS functions
https://github.com/numsu/nanocurrency-web-js

blockchain cryptocurrency cryptography nano nanocurrency

Last synced: 6 days ago
JSON representation

Toolkit for Nano cryptocurrency client side offline integrations without requiring NodeJS functions

Awesome Lists containing this project

README 

          
# nanocurrency-web



[![Build Status](https://travis-ci.org/numsu/nanocurrency-web-js.svg?branch=master)](https://travis-ci.org/numsu/nanocurrency-web-js)

[![npm version](https://badge.fury.io/js/nanocurrency-web.svg)](https://badge.fury.io/js/nanocurrency-web)

[![GitHub license](https://img.shields.io/github/license/numsu/nanocurrency-web-js)](https://github.com/numsu/nanocurrency-web-js/blob/master/LICENSE)



Toolkit for Nano cryptocurrency client side offline implementations allowing you to build web- and mobile applications using Nano without ever 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. And much more!



## Features



* Generate new HD wallets (BIP32/44 hierarchical deterministic) with a BIP39 mnemonic phrase (Used in Ledger hardware wallet)

* Generate new "legacy" Nano wallets with mnemonic phrases (Used in the Natrium wallet)

* Import HD wallets with a mnemonic phrase or a seed

* Import "legacy" wallets with the Nano mnemonic phrase or seed

* Sign send-, receive- and change (representative) blocks with a private key

* Convert Nano units

* Verify the signature of a block

* Sign any strings with the private key

* Verify the signature of any string with the public key

* Validate addresses and mnemonic words

* Runs in all web browsers and mobile frameworks built with Javascript (doesn't require server-side NodeJS functions)



---



## Installation

### From NPM



```console

npm install nanocurrency-web

```

### In web



```html



    NanocurrencyWeb.wallet.generate(...);



```



## Usage



| WARNING: do not use any of the keys or addresses listed below to send real assets! |

| --- |



### Wallets and accounts

The wallet is a hexadecimal string called a seed. From this seed you can deterministically derive millions of unique accounts. The first account in a wallet starts at index 0.



The library is able to generate, import and derive accounts for HD wallets and "legacy" Nano wallets. A HD wallet seed length is 128 hexadecimal characters while a "legacy" Nano wallet seed is 64 characters long.



These are the two most common wallet formats used in different applications. A good default is to support both of them. For example, when a user wants to import a wallet, you could generate both wallets and check if either wallet's account at index 0 has a frontier using [the accounts_frontiers RPC](https://docs.nano.org/commands/rpc-protocol/#accounts_frontiers) command.



```javascript

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.

// Custom entropy must be a 64 character hexadecimal string (32 bytes).

// If secure randomness is unavailable in the runtime, this call throws and you must

// provide custom entropy yourself.

// Notice, that losing the password will make the mnemonic phrase void

const wallet = wallet.generate(entropy?, password?)



// Generates a legacy wallet with a mnemonic phrase, seed and an account

// You can provide your own seed to be used instead.

// Custom seed must be a 64 character hexadecimal string (32 bytes).

// If secure randomness is unavailable in the runtime, this call throws and you must

// provide a custom seed yourself.

const wallet = wallet.generateLegacy(seed?)



// Import a wallet with the mnemonic phrase

// Words must be separated by spaces.

const wallet = wallet.fromMnemonic(mnemonic, seedPassword?)



// Import a wallet with the legacy mnemonic phrase

// Words must be separated by spaces.

const wallet = wallet.fromLegacyMnemonic(mnemonic)



// Import a wallet with a seed, the mnemonic phrase will be undefined since it's not possible to infer it from the seed

// The seed must be a 128 character hexadecimal string (64 bytes).

const wallet = wallet.fromSeed(seed)



// Import a wallet with a legacy seed

// The seed must be a 64 character hexadecimal string (32 bytes).

const wallet = wallet.fromLegacySeed(seed)



// Derive private keys for a seed, from and to are number indexes. The seed must be a

// 128 character hexadecimal string (64 bytes). The first account index is 0.

const accounts = wallet.accounts(seed, from, to)



// Derive private keys for a legacy seed, from and to are number indexes. The seed must be a

// 64 character hexadecimal string (32 bytes). The first account index is 0.

const accounts = wallet.legacyAccounts(seed, from, to)

```



```javascript

// The returned wallet JSON format is as follows. The mnemonic phrase will be undefined when importing with a seed, unless it's imported with a legacy seed

{

    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'

        }

    ]

}

```



### Blocks

There are three different types of blocks; send, receive and change. While all of these are called "state" blocks, they are interpreted differently based on the data they contain.



A send block means that the amount of Nano decreases in the account while a receive block means that the amount increases. If the amount stays the same, it's interpreted as a change (representative) block. You are able to change the representative also at the same time when sending or receiving. All blocks are signed with the account's private key.



The functions are designed to have user friendly usage, but they will return the block exactly the way as the network accepts them. All that is left is to publish the block to the network with the [process RPC command](https://docs.nano.org/commands/rpc-protocol/#process).



Always fetch the most up to date information for the account from the network using the [account_info RPC command](https://docs.nano.org/commands/rpc-protocol/#account_info).



If the account hasn't been opened yet (this is the first block), you will need to use the "genesis" as frontier: `0000000000000000000000000000000000000000000000000000000000000000`.



#### Signing a send block



```javascript

import { block } from 'nanocurrency-web'



const privateKey = '781186FB9EF17DB6E3D1056550D9FAE5D5BBADA6A6BC370E4CBB938B1DC71DA3'

const data = {

    // Current balance from account info

    walletBalanceRaw: '5618869000000000000000000000000',



    // Your wallet address

    fromAddress: 'nano_1e5aqegc1jb7qe964u4adzmcezyo6o146zb8hm6dft8tkp79za3sxwjym5rx',



    // The address to send to

    toAddress: 'nano_1q3hqecaw15cjt7thbtxu3pbzr1eihtzzpzxguoc37bj1wc5ffoh7w74gi6p',



    // From account info

    representativeAddress: 'nano_1stofnrxuz3cai7ze75o174bpm7scwj9jn3nxsn8ntzg784jf1gzn1jjdkou',



    // Previous block, from account info

    frontier: '92BA74A7D6DC7557F3EDA95ADC6341D51AC777A0A6FF0688A5C492AB2B2CB40D',



    // The amount to send in RAW

    amountRaw: '2000000000000000000000000000000',



    // Generate work on server-side or with a DPOW service

    // This is optional, you don't have to generate work before signing the transaction

    work: 'fbffed7c73b61367',

}



// Returns a correctly formatted and signed block ready to be sent to the blockchain

const signedBlock = block.send(data, privateKey)

```



#### Signing a receive block

```javascript

import { block } from 'nanocurrency-web'



const privateKey = '781186FB9EF17DB6E3D1056550D9FAE5D5BBADA6A6BC370E4CBB938B1DC71DA3'

const data = {

    // Your current balance in RAW from account info

    walletBalanceRaw: '18618869000000000000000000000000',



    // Your address

    toAddress: 'nano_3kyb49tqpt39ekc49kbej51ecsjqnimnzw1swxz4boix4ctm93w517umuiw8',



    // From account info

    representativeAddress: 'nano_1stofnrxuz3cai7ze75o174bpm7scwj9jn3nxsn8ntzg784jf1gzn1jjdkou',



    // From account info

    frontier: '92BA74A7D6DC7557F3EDA95ADC6341D51AC777A0A6FF0688A5C492AB2B2CB40D',



    // From the pending transaction

    transactionHash: 'CBC911F57B6827649423C92C88C0C56637A4274FF019E77E24D61D12B5338783',



    // From the pending transaction in RAW

    amountRaw: '7000000000000000000000000000000',



    // Generate the work server-side or with a DPOW service

    // This is optional, you don't have to generate work before signing the transaction

    work: 'c5cf86de24b24419',

}



// Returns a correctly formatted and signed block ready to be sent to the blockchain

const signedBlock = block.receive(data, privateKey)

```



#### Signing a change (representative) block

```javascript

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 with a DPOW service

    // This is optional, you don't have to generate work before signing the transaction

    work: '0000000000000000',

}



// Returns a correctly formatted and signed block ready to be sent to the blockchain

const signedBlock = block.representative(data, privateKey)

```

### Tools



#### Converting Nano units



Supported unit values are `RAW` and `NANO`.



```javascript

import { tools } from 'nanocurrency-web'



// Convert 1 Nano to RAW

const converted = tools.convert('1', 'NANO', 'RAW')



// Convert 1 RAW to Nano

const converted = tools.convert('1000000000000000000000000000000', 'RAW', 'NANO')

```



#### Verifying signatures and signing anything with the private key

Cryptocurrencies rely on asymmetric cryptography. This means that you can use the public key to validate the signature of a block or message that was signed with the private key.



For example implementing client side login with the password being the user's e-mail signed with their private key:



```javascript

import { tools } from 'nanocurrency-web'



const privateKey = '781186FB9EF17DB6E3D1056550D9FAE5D5BBADA6A6BC370E4CBB938B1DC71DA3'

const signed = tools.sign(privateKey, 'foo@bar.com')



// On the backend, verify the signature against the original UTF-8 string

```



You can also validate Nano blocks:

```javascript

import { tools } from 'nanocurrency-web'



const valid = tools.verifyBlock(publicKey, block)

```



You can challenge a user to prove ownership of a Nano address by making the user sign any UTF-8 string with the private key and then validating the signature with the public key. You can also derive the public key from the Nano address.

```javascript

import { tools } from 'nanocurrency-web'



const nanoAddress = 'nano_1pu7p5n3ghq1i1p4rhmek41f5add1uh34xpb94nkbxe8g4a6x1p69emk8y1d'

const privateKey = '3be4fc2ef3f3b7374e6fc4fb6e7bb153f8a2998b3b3dab50853eabe128024143'

const data = 'sign this'



// Make the user sign the data

const signature = tools.sign(privateKey, data)



// Infer the user's public key from the address (if not already known)

const publicKey = tools.addressToPublicKey(nanoAddress)



// Verify the signature using the public key, the signature and the original data

const validSignature = tools.verify(publicKey, signature, data)

```



#### Validating values

You are able to validate Nano addresses and mnemonic words.



```javascript

import { tools } from 'nanocurrency-web'



// Validate Nano address

const valid = tools.validateAddress('nano_1pu7p5n3ghq1i1p4rhmek41f5add1uh34xpb94nkbxe8g4a6x1p69emk8y1d')



// Validate mnemonic phrases

const valid = tools.validateMnemonic('edge defense waste choose enrich upon flee junk siren film clown finish luggage leader kid quick brick print evidence swap drill paddle truly occur')

```



#### Encrypting and decrypting strings

You can encrypt and decrypt UTF-8 strings to implement end-to-end encryption using the Nano address and private key. The public and private keys are converted to Curve25519 keys inside the library, and the encrypted output is returned as Base64. You may also provide a custom nonce as a 48 character hexadecimal string (24 bytes).



```javascript

import { box } from 'nanocurrency-web'



// Encrypt on device 1

// If you do not provide a custom nonce, this throws if the runtime does not provide

// a secure random implementation for nonce generation.

const encrypted = box.encrypt(message, recipientAddress, senderPrivateKey)



// Encrypt with a custom nonce

const encryptedWithCustomNonce = box.encrypt(

  message,

  recipientAddress,

  senderPrivateKey,

  nonce,

)



// Send the encrypted message to the recipient and decrypt on device 2

const decrypted = box.decrypt(encrypted, senderAddress, recipientPrivateKey)

```



## Contributions



You are welcome to contribute to the module. To develop, use the following commands.



* `npm install` to install dependencies

* `npm run build` to build and pack the code

* `npm run test` to run tests



Fork the project, make your changes and request them to be merged with a pull request. Issues are also welcome. If you have any questions, you can find me lurking around the Nano discord server.



## Donations



If this helped you in your endeavours and you feel like supporting the developer, please donate some Nano:



`nano_1iic4ggaxy3eyg89xmswhj1r5j9uj66beka8qjcte11bs6uc3wdwr7i9hepm`



If you prefer the old fashioned way, I also have a [GitHub Sponsors account](https://github.com/sponsors/numsu).