Skip to content

Commit

Permalink
Version 1.3.4
Browse files Browse the repository at this point in the history 
* Updated dependencies
* Improved documentation, JSDoc and typings
  • Loading branch information
@numsu
numsu committed Jun 8, 2021
1 parent 5196630 commit a546115
Show file tree
Hide file tree
Showing 6 changed files with 1,384 additions and 4,056 deletions.
2 changes: 1 addition & 1 deletion LICENSE
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
MIT License

Copyright (c) 2019 Miro Metsänheimo
Copyright (c) 2021 Miro Metsänheimo

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
Expand Down
215 changes: 119 additions & 96 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,37 +4,52 @@
[![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 compromising the user's keys by sending them out of their own device.
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

* Supports BIP32/44 hierarchial deterministic (HD wallet) private key derivation with Nano's derivation path
* Generate new HD wallets with a BIP39 mnemonic phrase (Also used in Ledger hardware wallet)
* Generate new legacy Nano wallets with mnemonic phrases (Also used in Natrium wallet)
* Import wallets with a mnemonic phrase or a seed
* Import wallets with the legacy Nano mnemonic phrase or seed
* Sign send-, receive- and change representative blocks with a private key
* Runs in all web browsers and mobile frameworks built with Javascript (doesn't require server-side NodeJS functions)
* Generate new HD wallets (BIP32/44 hierarchial 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
* Sign any strings with the private key, for example you can use the private key as the password by using a private key signature of any string as the password
* 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)

---

## Usage

## Installation
### From NPM

```console
npm install nanocurrency-web
```
### In web

```html
<script src="https://unpkg.com/[email protected]" type="text/javascript"></script>
<script type="text/javascript">
NanocurrencyWeb.wallet.generate(...);
</script>
```

## Usage

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

#### Wallet handling
### 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 used wallets in different applications. A best bet would be to support both of them. For example, when an user wants to import a wallet, you could always 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'
Expand All @@ -46,29 +61,29 @@ 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
const wallet = wallet.generateLegacey(seed?)
const wallet = wallet.generateLegacy(seed?)

// Import a wallet with the mnemonic phrase
const wallet = wallet.fromMnemonic(mnemonic, seedPassword?)

// Import a wallet with the legacy mnemonic phrase
const wallet = wallet.fromLegacyMnemonic(mnemonic)

// Import a wallet with a seed
// Import a wallet with a seed, the mnemonic phrase will be undefined since it's not possible to infer it from the seed
const wallet = wallet.fromSeed(seed)

// Import a wallet with a legacy hex seed
// Import a wallet with a legacy seed
const wallet = wallet.fromLegacySeed(seed)

// Derive private keys for a seed, from and to are number indexes
// Derive private keys for a seed, from and to are number indexes. 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
// Derive private keys for a legacy seed, from and to are number indexes. 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.
// 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',
Expand All @@ -83,38 +98,16 @@ const accounts = wallet.legacyAccounts(seed, from, to)
}
```
#### Signing a receive block
### 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.
```javascript
import { block } from 'nanocurrency-web'

const privateKey = '781186FB9EF17DB6E3D1056550D9FAE5D5BBADA6A6BC370E4CBB938B1DC71DA3';
const data = {
// Your current balance in RAW
walletBalanceRaw: '18618869000000000000000000000000',

// Your address
toAddress: 'nano_3kyb49tqpt39ekc49kbej51ecsjqnimnzw1swxz4boix4ctm93w517umuiw8',

// From wallet info
representativeAddress: 'nano_1stofnrxuz3cai7ze75o174bpm7scwj9jn3nxsn8ntzg784jf1gzn1jjdkou',
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.
// From wallet info
frontier: '92BA74A7D6DC7557F3EDA95ADC6341D51AC777A0A6FF0688A5C492AB2B2CB40D',
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).
// From the pending transaction
transactionHash: 'CBC911F57B6827649423C92C88C0C56637A4274FF019E77E24D61D12B5338783',
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).
// From the pending transaction in RAW
amountRaw: '7000000000000000000000000000000',

// Generate the work server-side or with a DPOW service
work: 'c5cf86de24b24419',
}

// Returns a correctly formatted and signed block ready to be sent to the blockchain
const signedBlock = block.receive(data, privateKey)
```
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
Expand All @@ -123,7 +116,7 @@ import { block } from 'nanocurrency-web'

const privateKey = '781186FB9EF17DB6E3D1056550D9FAE5D5BBADA6A6BC370E4CBB938B1DC71DA3';
const data = {
// Current balance from wallet info
// Current balance from account info
walletBalanceRaw: '5618869000000000000000000000000',

// Your wallet address
Expand All @@ -132,25 +125,58 @@ const data = {
// The address to send to
toAddress: 'nano_1q3hqecaw15cjt7thbtxu3pbzr1eihtzzpzxguoc37bj1wc5ffoh7w74gi6p',

// From wallet info
// From account info
representativeAddress: 'nano_1stofnrxuz3cai7ze75o174bpm7scwj9jn3nxsn8ntzg784jf1gzn1jjdkou',

// Previous block, from wallet info
// 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 change representative block
#### 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'

Expand All @@ -169,40 +195,16 @@ const data = {
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)
```
#### Verifying signatures
Cryptocurrencies rely on public key cryptographgy. This means that you can use the public key to validate the signature of the block that is signed with the private key.
```javascript
import { tools } from 'nanocurrency-web'
### Tools
const valid = tools.verifyBlock(publicKey, block)
```
##### Using signature verification to prove ownership of the address
You are able to challenge an user to prove ownership of a Nano address simply by making the user sign any string with the private key and validating the signature.
```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)

```
#### Converting units
#### Converting Nano units
Supported unit values are RAW, NANO, MRAI, KRAI, RAW.
Expand All @@ -216,51 +218,72 @@ const converted = tools.convert('1', 'NANO', 'RAW')
const converted = tools.convert('1000000000000000000000000000000', 'RAW', 'NANO')
```
#### Signing any data with the private key
#### Verifying signatures and signing anything with the private key
Cryptocurrencies rely on asymmetric cryptographgy. This means that you can use the public key to validate the signature of the block that is 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. Make sure that you double check the signature on the back-end side with the public 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, '[email protected]')

// On the backend, verify that the signed value matches the hashed signature in your database
```
#### Validating values
You can also validate Nano blocks:
```javascript
import { tools } from 'nanocurrency-web'

const valid = tools.verifyBlock(publicKey, block)
```
You are able to challenge an user to prove ownership of a Nano address simply by making the user sign any string with the private key and then validating the signature with the public key. You are even able to derive the public key from the Nano address.
```javascript
import { tools } from 'nanocurrency-web'

// Validate Nano address
const valid = tools.validateAddress('nano_1pu7p5n3ghq1i1p4rhmek41f5add1uh34xpb94nkbxe8g4a6x1p69emk8y1d')
const nanoAddress = 'nano_1pu7p5n3ghq1i1p4rhmek41f5add1uh34xpb94nkbxe8g4a6x1p69emk8y1d'
const privateKey = '3be4fc2ef3f3b7374e6fc4fb6e7bb153f8a2998b3b3dab50853eabe128024143'
const data = 'sign this'

// Validate mnemonic words
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')
// 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'

### In web
// Validate Nano address
const valid = tools.validateAddress('nano_1pu7p5n3ghq1i1p4rhmek41f5add1uh34xpb94nkbxe8g4a6x1p69emk8y1d')

```html
<script src="https://unpkg.com/[email protected]" type="text/javascript"></script>
<script type="text/javascript">
NanocurrencyWeb.wallet.generate(...);
</script>
// 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')
```
---
## 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
* `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, feel free to donate some Nano:
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).
Loading

0 comments on commit a546115

Please sign in to comment.