bitmark-lib

bitmark-lib

Install

$ npm install bitmark-lib

Set up

var bitmarkLib = require('bitmark-lib');

Usage

Seed

Set up

var Seed = bitmarkLib.Seed;

Seed is where everything starts for an entity which wants to use bitmark services. A seed is used to generate:

• auth key: for authentication of transactions (issue or transfer)
• encryption key: for encryption of assets

To create a new random seed:

var seed = new Seed();

There are 2 optional parameters for the Seed constructor: network and version. The default for network is livenet, and the only supported version now is 1.

var seed = new Seed('testnet');
var seed = new Seed('testnet', 1);

Losing the seed means losing the control over bitmarks and assets of the entity. Thus, a seed should be backed up by saving its string format in a secure place, and be imported when there are operations which require authentication or encryption.

var backup = seed.toString(); // using toBase58 is equivalent
var restore = Seed.fromString(backup);
var isValidSeedString = Seed.isValid(backup); // check whether a string is in valid format

Passing a counter to the seed, it will create a new 32-byte secret key

var key = seed.generateKey(999);

Note: the counter 999 and 1000 are preserved to generate auth key and encryption key

Methods

• generateKey(counter) — returns 32 bytes in a Buffer object
• toString() — returns the seed in string format
• toBase58() — returns the seed in Base58 format (same as toString)
• getNetwork() — returns the network of the seed, either livenet or testnet
• getVersion() — returns the version of the seed
• getCore() — returns the core of the seed, for keypair derivation

Auth Key

Set up

var AuthKey = bitmarkLib.AuthKey;

Instantiate

To create the auth key from a new seed:

var authKey = AuthKey.fromSeed(new Seed());

To instantiate a AuthKey object:

var authKey01 = new AuthKey();

There are 2 optional parameters for the AuthKey constructor: network and key type. The default for network is livenet, and the default for key type is ed25519.

var authKey02 = new AuthKey('testnet');
var authKey03 = new AuthKey('livenet', 'ed25519');

To parse the private key from the KIF string:

var authKey = AuthKey.fromKIF('cELQPQoW2YDWBq37V6ZLnEiHDD46BG3tEvVmj6BpiCSvQwSszC');

To parse the private key from buffer:

var authKey = AuthKey.fromBuffer('75d954e8f790ca792502148edfefed409d3da04b49443d390435e776821252e26c60fe96ba261d2f3942a33d2eaea2391dfb662de79bc0c4ef53521ce8b11c20', 'testnet', 'ed25519');

The buffer can be either a hexadecimal string or a Buffer object. For ed25519, we can input a seed (32 bytes) or a full private key (64 bytes).

Methods

• toBuffer() — returns a Buffer object containing the private key
• toString() — returns toBuffer() in hexadecimal format
• toKIF() — returns the private key in KIF format.
• getNetwork() — returns either livenet or testnet, depending on the key
• getType() — returns the key type (currently only ed25519)
• getAccountNumber() — returns an AccountNumber object (see the next section)

AccountNumber

Set up

var AccountNumber = bitmarkLib.AccountNumber;

Instantiate

To instantiate an AccountNumber object from an AuthKey:

var authKey = AuthKey.fromKIF('cELQPQoW2YDWBq37V6ZLnEiHDD46BG3tEvVmj6BpiCSvQwSszC');
var accountNumber = authKey.getAccountNumber()

To instantiate an AccountNumber object from an account number string:

var accountNumber = new AccountNumber('bxnT1iqAWFWM2MpSNGMHTq92Y27n81B3ep4vFcTpra4AEU9q7d');
var sameAccountNumber = AccountNumber.fromString('bxnT1iqAWFWM2MpSNGMHTq92Y27n81B3ep4vFcTpra4AEU9q7d');

To instantiate an AccountNumber object from a Buffer object:

var buffer = new Buffer('73346e71883a09c0421e5d6caa473239c4438af71953295ad903fea410cabb44', 'hex');
var accountNumber = new AccountNumber(buffer, 'testnet', 'ed25519');
var sameAccountNumber01 = AccountNumber.fromBuffer(buffer, 'testnet', 'ed25519');
var sameAccountNumber02 = AccountNumber.froMBuffer('73346e71883a09c0421e5d6caa473239c4438af71953295ad903fea410cabb44', 'testnet', 'ed25519');

Note:

• network and keytype are optional, the defaults are livenet and ed25519.
• When instantiating a AccountNumber from a Buffer object using the constructor function, input the Buffer object instead of a hexadecimal string value.

Validation

AccountNumber.isValid('erxs7Li15xcioSpGLi1kPhA4vNvJSJYEUnTzU4oJ989coEuUv;'); // returns false because of bad account number string
AccountNumber.isValid('ayUWeSeJEcATAHQTBU1qkVcEh9V12cnfCeFWAh1Jq7NdVMjH5q', 'testnet'); // returns false because of wrong network
AccountNumber.isValid('erxs7Li15xcioSpGLi1kPhA4vNvJSJYEUnTzU4oJ989coEuUvb', 'testnet'); // returns true

Methods

• toString() — returns the account number as a string
• getNetwork() — returns either livenet or testnet, depending on the account number
• getPublicKey() — returns the public key as a hexadecimal string value
• getKeyType() — returns the key type (currently only ed25519)

Records

Asset Record

Set up

var Asset = bitmarkLib.Asset

Instantiate

To instantiate an Asset record object:

var asset = new Asset()
      .setName('Asset name')
      .addMetadata('description', 'this is asset description')
      .setFingerprint('73346e71883a09c0421e5d6caa473239c4438af71953295ad903fea410cabb44')
      .sign(authKey);

Methods

• isSigned() — returns true if the asset record is signed
• getName() — returns the string value for an Asset's Name property
• setMetadata(jsonMetadata) - set the metadata for the asset
• importMetadata(stringMetadata) - set the metadata in string format
• addMetadata(key, value) - add the metadata to existing metadata set of the asset
• removeMetadata(key) - remove a specific metadata from existing metadata set
• getMetadata() - get the json metadata
• getFingerprint() — returns the hexadecimal value for an Asset's Fingerprint property
• getRegistrant() — returns an AccountNumber object specifying the Asset's Registrant property
• getSignature() — returns the Asset object's signature buffer
• getId() — returns the Asset object's 'AssetIndex' as a string value

Issue Record

Set up

var Issue = bitmarkLib.Issue

Instantiate

To instantiate an Issue record object:

var issue = new Issue()
      .fromAsset(asset)
      .setNonce(1)
      .sign(authKey);

Note: fromAsset() can receive either an Asset object or an asset-id string.

Methods

• isSigned() — returns true if the issue record is signed
• getOwner() — returnss an AccountNumber object specifying the Issue record's Owner property
• getSignature() — returns the Issue object's signature buffer
• getAsset(): returns the Issue record's corresponding AssetIndex as a string value
• getId() — returns a hexadecimal string id for the Issue record

Transfer

Set up

var Transfer = bitmarkLib.Transfer

Instantiate

To instantiate a Transfer record object:

var transfer = new Transfer()
      .fromTx(previousTransfer)
      .toAccountNumber(newOwner)
      .sign(authKey);

Note: fromTx() can receive either an Issue or Transfer object or an id string from either an Issue or Transfer object.

Methods

• isSigned() — returns true if the transfer record is signed
• getOwner() — returns an AccountNumber object specifying the the Transfer record's Owner property
• getSignature(): returns the Transfer object's signature buffer
• getPreTxId(): returns a hexadecimal string of the Id for the previous record in the chain-of ownership (either an Issue record or Transfer record) — the same as a record's Link property in the blockchain data structure
• getId() — returns a hexadecimal string id for the Transfer record

Utilities

Fingerprint

Set up

var bitmarkLib = require('bitmark-lib');
var fingerprint = bitmarkLib.util.fingeprint;

Methods

• fromBuffer(Buffer) - returns a fingerprint string from buffer content
• fromString(string) - returns a fingerprint string from string content

--

License

Copyright (c) 2014-2017 Bitmark Inc ([e-mail]).

Permission to use, copy, modify, and distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.