nimiq/core-js

Official JavaScript implementation of the Nimiq protocol

Nimiq Blockchain

Nimiq is a frictionless payment protocol for the web.

Resources

• Nimiq White Paper: High-level introduction of the Nimiq payment protocol.
• Nimiq Developer Reference: Details of the protocol architecture.
• Core API Documentation: Documentation of the Nimiq Core library API.
• Node.js Client Documentation: Usage and configuration documentation for the Nimiq Node.js Client.
• JSON-RPC Client Documentation: Usage instructions for the Nimiq JSON-RPC Client.
• Docker Documentation: Instructions on setting up a Nimiq Node using Docker.
• Packaging Documentation: Instructions on how to build binary packages for Linux (.deb and/or RPM) from this source code.

Demo

Check out our Testnet.

Packages

Prebuilt binary packages

For users looking to run a standalone Nimiq node (which is also capable of mining), see our Downloads page for installable Linux and Windows binary packages.

NPM Packages

For developers looking to include Nimiq support on their applications, there are two npm packages available:

• @nimiq/core: Module for use in node.js applications.
• @nimiq/core-web: Module for use in client-side (browser) applications (includes the same files that are available from our CDN).

Quickstart

1. Install Node.js >= v16.20.2.
2. On Ubuntu and Debian, install git and build-essential: sudo apt-get install -y git build-essential.
   • On other Linux systems, install git, python3, make, gcc and gcc-c++.
   • For MacOS or Windows, check here for git and here for compilation tools.
3. Install yarn globally: sudo npm install -g yarn.
4. Install gulp globally: yarn global add gulp.
5. Clone this repository: git clone https://github.com/nimiq/core-js.
6. Build the project: cd core-js && yarn && yarn build.
7. Open clients/browser/index.html in your browser.

Web Developers

Simple Web Application on top of Nimiq

A good way to get started is to have a look at the most simple web application on top of the Nimiq Blockchain.

Getting Started

Follow the Quickstart guide or make use of our CDN:

<script src="https://cdn.nimiq.com/latest/nimiq.js"></script>

Browser client

Open clients/browser/index.html in your browser or include <script src="dist/nimiq.js"></script> in your project.

Node.js client

To run a Node.js client you will need a publicly routable IP, Domain, and SSL Certificate (get a free certificate at letsencrypt.org). Start the client by running clients/nodejs/nimiq with the respective configuration.

Test and Build

Run Testsuite

• yarn test runs browser and Node.js tests.
• yarn test-browser runs the testsuite in your browser only.
• yarn test-node runs the testsuite in Node.js only.

Run ESLint

yarn lint runs the ESLint javascript linter.

Build

Executing yarn build concatenates all sources into dist/{web,web-babel,web-crypto,node}.js

Contribute

If you'd like to contribute to the development of Nimiq please follow our Code of Conduct and Contributing Guidelines.

License

This project is under the Apache License 2.0.

core-js's Issues

Implement GPU-based mining

Evaluate DoS resilience

Create bower package

Add persistent peer address storage

Program state does not correctly update when using multiple tabs at the same time

e.g. blockchain head does not update when receiving a new block that is already in the database.

Setup backbone network

• Related issues: #23

Setup central management, monitoring

Mining should not start until consensus is established

Needs to consider the corner case that consensus might never be established if connection to the network fails.

Don't accept transactions with value+fee === 0

_verifyTransaction and _verifyTransactionBalance in Mempool.js doen't check if value+fee of the transaction === 0

Create backbone node setup script (with letsencrypt)

Create AWS/Docker image for backbone nodes

• Related issues: #29

ICE/Stun server configuration

Introduce transaction type

Simulate high peer join/leave rates

Basic ICO website infrastructure

• Hoster: GitHub Pages
• Cloudflare: Currently free plan
• SSL: Currently shared cloudflare certificate
• Email

Reject local/private/invalid ips/hostnames

• Reject invalid IPs
• Reject invalid hostnames in WS addresses (e.g. wss://localhost, wss://127.0.0.1, wss://192.168.x.x, etc.)

Weird Private Key implementation

In contrast to the PublicKey class that is well-used across the core, the PrivateKey implementation seems to be a copy-pasted version (actually in line 12 there is PublicKey instead of PrivateKey) that is never really used.

The problem is that, again in contrast to pub keys, private keys cannot be exported in 'raw' format in the subtle crypto lib we are using. Hence, while the 65 byte size of pub keys makes sense, the private key can only be represented as, e.g., 'pkcs8', which requires different handling.

Issue #2 also indicates that the private key topic is still somewhat open.

I think the current implementation is more like a stub. Depending on what we need the class for in the long run (serializing it for wallet portability maybe?), the implementation should reflect the way it is exported from the crypto lib.

TL;DR: I don't see how to use the PrivateKey class as-is (or where it is used), so either it needs additional explanation or another implementation.

BlockUtils conversion does not work both ways

I added new tests specifying the functionality of the new BlockUtils class.
Build #18 is now failing, because converting a difficulty to compact and back does not return the same difficulty.

This is easy to verify for several difficulties (e.g., 250) and the following code:
difficulty == BlockUtils.compactToDifficulty(BlockUtils.difficultyToCompact(difficulty))

Moreover, I have a question regarding valid values for difficulty:
What values are allowed for a difficulty? 0 does not seem to be valid, since BlockUtils divides by the difficulty. Is Policy.BLOCK_TARGET_MAX the maximal value?

• Verify bug
• Fix bug
• Answer question regarding valid range of difficulties

Create backbone node setup guide

Investigate maximum WebSocket/WebRTC message size

We might need to split large P2P messages (e.g. blocks) into several WS/RTC messages.

http://viblast.com/blog/2015/2/5/webrtc-data-channel-message-size/

Transaction verification does not mind fees

The method _verifyTransactionBalance in Mempool.js does not mind the transaction fees.

Transpile code for older/shitty browsers

e.g. Safari

Miner should construct blocks that maximise profit

Maximise reward per byte.

Prepare AccountsTree for Mini-Blockchain-Scheme

In order to keep balance proofs small, we should reduce the maximum number of children per node from 256 to 16.

Introduce account type

pushTransaction() in Mempool is incorrectly recording sender public keys

The property for a sender public key in a transaction is senderPubKey, but Mempool.pushTransaction() is using transaction.publicKey instead, which means every transaction (after the first one) gets rejected because the code thinks they all have the same sender public key (i.e. undefined).

Create tests for Accounts/AccountsTree class

There are already a couple of Accounts/AccountsTree tests to start with:
https://github.com/nimiq-network/core/tree/master/src/test/specs/generic/consensus/accounts

Accounts: e.g.

• complex blocks
• invalid blocks

AccountsTree: e.g.

• deep trees
• large trees
• persistent storage (?)

Create npm package

Exception in importPrivate in Crypto.js

The importPrivate in Crypto.js throws the following Exception:
Failed to execute 'importKey' on 'SubtleCrypto': 5 arguments required, but only 2 present.

If you want, I can add a test to the crypto.spec.js

Create tests for Mempool class

Use ASIC-resistant proof of work

Cross-browser testing Desktop

Don't reconnect forever when the peer isn't sending any good blocks

Needs to consider the case that the peer is on a long fork.

Get balance 0 for unknown address

Currently a call to getBalance(address) in Accounts.js gives false for an unknown address. Probably getting 0 or a Balance instance with value 0 would be desirable.

Sanity of timestamp not checked

The following might be a small vulnerability:
Blocks with an arbitrary timestamp seem to get accepted as long as they are at a later date then the current head. If a malicious miner then commits a valid block with the last possible timestamp and this block becomes the new head, any block mined on top of that with a honest valid timestamp will be rejected because it is not later then the head.

Update: The malicious miner could use this issue for example by submitting valid blocks with timestamps that increment by a rather big amount, e.g. one week. Thereby, the difficulty will decrease and it will be easy for the malicious miner to mine a lot of blocks. Of course the total work doesn't imcrement that much by doing so, so another branch can outperform that malicious blockchain. However, the code must not get stuck on that malicious blockchain. A possible solution might be to not accept heads that have a timestamp much later then the current time in _isValidExtension in Blockchain.js.

Cross-browser testing Mobile

Measure behaviour of long-running node/miner

• Look for memory leaks
• Check hashrate degradation (NodeJS)

Create tests for Blockchain class

Remove peer address from Network._activeAddresses if handshake didn't finish

Simulate large transaction volume

Setup virtual private TestNet

• Related issues: #23

Use cloud service(s) to setup a large number of nodes (1k-100k), both backbone and browser.

Prepare Blockchain for Mini-Blockchain-Scheme

In order to verify balance proofs efficiently, accountsHash in BlockHeader should correspond to the AccountsTree hash after the block is applied, instead of before.

Use double sha256 as hash function

Simulate slow/unreliable network

Save Private Key to Wallet after Import

Importing a private key to the Wallet does not seem to be fully implemented yet.
I guess after creating a CryptoKey from an ArrayBuffer using importPrivate(privateKey) it should be stored in _keys and if the wallet is persistent also in the WalletStore ?

Update: Or probably it would be better to actually remove that import method and then do importing by creating a new Wallet instance with the keys to import and then maybe have a setPersistent Method in the wallet that can save the keys to the WalletStore?

Send reject messages for invalid blocks/transactions

Also add logic to deal with reject messages and/or apis to expose them.

Add lint/static analyzer to toolchain

Set and validate Message length & checksum

Add version fields to models

Primarily models persisted in the blockchain:

• blocks
• transactions
• ...

Might also be relevant for models exchanged via network.

Implement block reward reduction / total coin supply limit

Needs to consider pre-allocated coins in genesis block / founders rewards.

DoS resilience: ban misbehaving peers

e.g. peers that keep sending junk data