bitmention-api v0.29.1
Bitmention API
Bitmention Platform core features and Bitmention API library for both Node.js and browser.
Installation
npm install bitmention-api --save
In Node.js:
const BitmentionAPI = require('bitmention-api');
In browser:
<script src="./node_modules/bitmention-api/dist/bitmention-api.min.js"></script>
You can use bitmention-api
even within Web Workers.
Usage
const Bitmention = BitmentionAPI.create(BitmentionAPI.TESTNET_CONFIG);
Seed
You can create a new random seed:
const seed = Bitmention.Seed.create();
console.log(seed.phrase); // 'sun mirror source ritual scheme sample hard web organ fetch lock silk calm scare planet'
console.log(seed.address); // '3N2ndbiafubL4kAF3CUc6weLnFPePRry14W'
console.log(seed.keyPair); // { privateKey: "BHZuQNdMDfZXRjKmwT3Yu36Wxddujm4pA9LnU1TSgw27", publicKey: "9QoqQ9iVrn1PoaTXVy5JFXPUzBk7h1uu86VhXJDtebgZ"}
That seed may be encrypted with a password:
const password = '0123456789';
const encrypted = seed.encrypt(password);
console.log(encrypted); // 'U2FsdGVkX18tiYXXYp+JVxM9MJexFUu9XV42yxmw6Ohw0MPTwGPsz8N2j34NWT+uYtheaflVsamVtiUOh2yPhbT2jx/KNkSNJCeH4jTCdXRCqtYEiB4wbkw9pHNCkj7+o4b2kbvXLA7eOCd2JtpPhg=='
And decrypted (with the same password, of course):
const restoredPhrase2 = Bitmention.Seed.decryptSeedPhrase(encrypted, password);
console.log(restoredPhrase); // 'hole law front bottom then mobile fabric under horse drink other member work twenty boss'
Being called with a wrong password Bitmention.Seed.decryptSeedPhrase()
throws an exception.
You also can create a Seed
object from an existing seed:
const anotherSeed = Bitmention.Seed.fromExistingPhrase('a seed which was backed up some time ago');
console.log(seed.phrase); // 'a seed which was backed up some time ago'
console.log(seed.address); // '3N3dy1P8Dccup5WnYsrC6VmaGHF6wMxdLn4'
console.log(seed.keyPair); // { privateKey: '2gSboTPsiQfi1i3zNtFppVJVgjoCA9P4HE9K95y8yCMm', publicKey: 'CFr94paUnDSTRk8jz6Ep3bzhXb9LKarNmLYXW6gqw6Y3' }
Node API
Right now only the first version of Node API is available. If you want to contribute to the new versions of Bitmention API please see the section below.
Sending transactions
You will need a pair of keys from an account with a balance to send transactions:
const seed = Bitmention.Seed.fromExistingPhrase('a seed from an account with some funds');
Issue transaction
const issueData = {
name: 'Your token name',
description: 'Some words about it',
// With given options you'll have 100000.00000 tokens
quantity: 10000000000,
precision: 5,
// This flag defines whether additional emission is possible
reissuable: false,
fee: 100000000,
timestamp: Date.now()
};
Bitmention.API.Node.v1.assets.issue(issueData, seed.keyPair).then((responseData) => {
console.log(responseData);
});
Transfer transaction
const transferData = {
// An arbitrary address; mine, in this example
recipient: '3EmePqU4993wsdfN12MkTRiDquozgJn1WfA',
// ID of a token, or BTMNT
assetId: 'BTMNT',
// The real amount is the given number divided by 10^(precision of the token)
amount: 10000000,
// The same rules for these two fields
feeAssetId: 'BTMNT',
fee: 100000,
// 140 bytes of data (it's allowed to use Uint8Array here)
attachment: '',
timestamp: Date.now()
};
Bitmention.API.Node.v1.assets.transfer(transferData, seed.keyPair).then((responseData) => {
console.log(responseData);
});
Reissue transaction
const reissueData = {
// Asset ID which is to be additionnaly emitted
assetId: '5xN8XPkKi7RoYUAT5hNKC26FKCcX6Rj6epASpgFEYZss',
// Additional quantity is the given number divided by 10^(precision of the token)
quantity: 100000000,
reissuable: false,
fee: 100000000,
timestamp: Date.now()
};
Bitmention.API.Node.v1.assets.reissue(reissueData, seed.keyPair).then((responseData) => {
console.log(responseData);
});
Burn transaction
const burnData = {
// Asset ID and its quantity to be burned
assetId: '5xN8XPkKi7RoYUAT5hNKC26FKCcX6Rj6epASpgFEYZss',
quantity: 20000000000,
fee: 100000,
timestamp: Date.now()
};
Bitmention.API.Node.v1.assets.burn(burnData, seed.keyPair).then((responseData) => {
console.log(responseData);
});
Lease transaction
const leaseData = {
recipient: '5xN8XPkKi7RoYUAT5hNKC26FKCcX6Rj6epASpgFEYZss',
// Both amount and fee may be presented as divided by 10^8 (8 is Bitmention precision)
amount: 1000000000, // 10 Bitmention
fee: 100000, // 0.001 Bitmention
timestamp: Date.now()
};
Bitmention.API.Node.v1.leasing.lease(leaseData, seed.keyPair).then((responseData) => {
console.log(responseData);
});
Cancel Leasing transaction
const cancelLeasingData = {
// Related Lease transaction ID
transactionId: '2kPvxtAit2nsumxBL7xYjvaWYmvmMfDL5oPgs4nZsHvZ',
fee: 100000,
timestamp: Date.now()
};
Bitmention.API.Node.v1.leasing.cancelLeasing(cancelLeasingData, seed.keyPair).then((responseData) => {
console.log(responseData);
});
Create Alias transaction
const createAliasData = {
// That's a kind of a nickname you attach to your address
alias: 'xenohunter',
fee: 100000,
timestamp: Date.now()
};
Bitmention.API.Node.v1.aliases.createAlias(createAliasData, seed.keyPair).then((responseData) => {
console.log(responseData);
});
Getting the information from Node
The most used GET requests are those related to balances and transactions history.
Bitmention balance
There are two types of Bitmention balance: simple, with optional confirmations
parameter, and detailed, showing different types of Bitmention balance.
With the first type, without additional arguments, you get the current balance on an address:
Bitmention.API.Node.v1.addresses.balance('3EmePqU4993wsdfN12MkTRiDquozgJn1WfA').then((balance) => {
console.log(balance);
});
If you pass an optional confirmations
argument, you get the balance with N confirmations, i.e. the balance as it was N blocks ago from the moment:
Bitmention.API.Node.v1.addresses.balance('3EmePqU4993wsdfN12MkTRiDquozgJn1WfA', 100).then((balance) => {
console.log(balance);
});
For the second type, there is a separate method:
Bitmention.API.Node.v1.addresses.balanceDetails('3EmePqU4993wsdfN12MkTRiDquozgJn1WfA').then((balanceDetails) => {
console.log(balanceDetails);
});
Token balances
You can get the list of all balances on an address:
Bitmention.API.Node.v1.assets.balances(address).then((balancesList) => {
console.log(balancesList);
});
You also can get the balance of a given token:
Bitmention.API.Node.v1.assets.balance(address, assetId).then((balance) => {
console.log(balance);
});
Token distribution
A very useful method allowing you to get a map with balances of all addresses in possession of a token:
Bitmention.API.Node.v1.assets.distribution(assetId).then((distributionMap) => {
console.log(distributionMap);
});
Transactions
Every transaction in the blockchain has its own ID. You can both get one by ID, or get a list of all recent transactions.
Bitmention.API.Node.v1.transactions.get('TonZDUUaBojXXGNxmdkiyTYK97PaqtUUMuEkPhGU9ZR').then((tx) => {
console.log(tx);
});
To get the list you need to provide an address which is either the sender or the recipient of the transactions in the resulting list:
Bitmention.API.Node.v1.transactions.getList('3EmePqU4993wsdfN12MkTRiDquozgJn1WfA').then((txList) => {
console.log(txList);
});
One of the concepts in most blockchains is UTX, unconfirmed transactions pool. During the time between blocks appearance, transactions from users are stored in it.
There are methods to get the size of UTX pool and UTX pool itself (note that the address is not needed here):
Bitmention.API.Node.v1.transactions.utxSize().then((utxSize) => {
console.log(utxSize);
});
Bitmention.API.Node.v1.transactions.utxGetList().then((utxList) => {
console.log(utxList);
});
Also if a transaction is still in UTX pool and you know its ID, you can get only it from UTX:
Bitmention.API.Node.v1.transactions.utxGet('TonZDUUaBojXXGNxmdkiyTYK97PaqtUUMuEkPhGU9ZR').then((tx) => {
console.log(tx);
});
Aliases
Aside from creating an alias, you also can get the list of aliases bound to an address, or get the address related to the given alias.
Bitmention.API.Node.v1.aliases.byAddress('3EmePqU4993wsdfN12MkTRiDquozgJn1WfA').then((aliasesList) => {
console.log(aliasesList);
});
Bitmention.API.Node.v1.aliases.byAlias('xenohunter').then((address) => {
console.log(address);
});
Blocks
Everything is simple here. You can get the whole block by its signature (get()
) or height (at()
). Method height()
returns the current height of the Bitmention blockchain. The names of the remaining methods speak for themselves.
Bitmention.API.Node.v1.blocks.get(signature).then((block) => console.log(block));
Bitmention.API.Node.v1.blocks.at(height).then((block) => console.log(block));
Bitmention.API.Node.v1.blocks.height().then((currentHeight) => console.log(currentHeight));
Bitmention.API.Node.v1.blocks.first().then((firstBlock) => console.log(firstBlock));
Bitmention.API.Node.v1.blocks.last().then((lastBlock) => console.log(lastBlock));
Configuration
The configuration is changeable even during the runtime. The structure of the config is following:
const newConfig = {
// The byte allowing to distinguish networks (mainnet, testnet, devnet, etc)
networkByte: Bitmention.constants.MAINNET_BYTE,
// Node and Matcher addresses, no comments here
nodeAddress: 'https://nodes.bitmentionnodes.com',
matcherAddress: 'https://matcher.bitmentionnodes.com',
// If a seed phrase length falls below that value an error will be thrown
minimumSeedLength: 50
};
All fields are optional, only filled ones will be replaced.
You can change the config like that:
Bitmention.config.set(newConfig);
Tools
Get address from public key
const address = Bitmention.tools.getAddressFromPublicKey('GL6Cbk3JnD9XiBRK5ntCavSrGGD5JT9pXSRkukcEcaSW');
console.log(address); // '3EmDU9SFDJhiPC5uYhoavEozSQoEh6m5uun'
Common pitfalls
Bitmention ID in the library and in the blockchain
One of the trickiest things about Bitmention blockchain is that Bitmention ID equals empty string. In the first version on Node API it also equals to empty string. That is an unobvious and potentially dangerous behavior. Therefore in this library Bitmention ID strictly equals string BTMNT
. Please mind that fact.
Fee asset choice for transfer transactions
There is only one type of transactions (currently) in which we can use arbitrary tokens as fees. The only limitation is that the Node to which you connect must support the token you use as fees. Please note that transactions with the Bitmention fee will be prior over transactions with fees in other tokens.
Impossibility of transactions with the absolutely same data
Transaction IDs are built from all the data in a transaction except the signature. That process is deterministic. So there cannot be two transactions with the absolutely same data.
Delays in the leasing process
For the security reasons all leased Bitmention take effect only after 1000 blocks. Don't worry when your generating balance isn't updated right away.
Different types of Bitmention balance
There is the most understandable type of Bitmention balance. It is the regular balance. It is served through Bitmention.API.Node.v1.addresses.balance()
. There are also several types of Bitmention balance related to leasing and the delays in its processing.
- Regular — that's how much Bitmention you have, including those you leased;
- Available — the same as regular only without Bitmention you leased;
- Effective — available plus those Bitmention which is leased to you;
- Generating — the minimal effective for last 1000 blocks;
- Leased — the amount you leased to other addresses.
Available balance you can lease and spend.
Generating balance gives you mining power.
Tests
cd ./node_modules/bitmention-api/
npm install
npm run test # to run tests in Node.js
npm run test-browser # to run test in Chrome browser
Test configuration may be changed in the ./node_modules/bitmention-api/karma.conf.js file.
Tools
- TypeScript - Typed superset of JavaScript
- Karma - Test runner
- Chai - Assertion library
Authors
- Phil Filippak - Initial work
- Daniil Tsigelnitskiy - TypeScript expertise
License
This project is licensed under the MIT License - see the LICENSE.md file for details.