Official JavaScript driver for Planetmint to create transactions in Node.js and the browser.
Compatibility
| Planetmint Server | Planetmint JavaScript Driver |
|---|---|
2.x.x |
0.0.x |
Table of Contents
- Installation and Usage
- Planetmint Documentation
- Speed Optimizations
- Development
- Release Process
- Authors
- Licenses
Installation and Usage
npm install planetmint-driverconst driver = require('planetmint-driver')
// or ES6+
import driver from 'planetmint-driver'Example: Create a transaction
const driver = require('planetmint-driver')
const base58 = require('bs58');
const crypto = require('crypto');
const { Ed25519Sha256 } = require('crypto-conditions');
// Planetmint server instance (e.g. https://example.com/api/v1/)
const API_PATH = 'http://localhost:9984/api/v1/'
// Create a new keypair.
const alice = new driver.Ed25519Keypair()
// Construct a transaction payload
const tx = driver.Transaction.makeCreateTransaction(
// Define the asset to store, in this example it is the current temperature
// (in Celsius) for the city of Berlin.
{ city: 'Berlin, DE', temperature: 22, datetime: new Date().toString() },
// Metadata contains information about the transaction itself
// (can be `null` if not needed)
{ what: 'My first Planetmint transaction' },
// A transaction needs an output
[ driver.Transaction.makeOutput(
driver.Transaction.makeEd25519Condition(alice.publicKey))
],
alice.publicKey
)
// Sign the transaction with private keys
const txSigned = driver.Transaction.signTransaction(tx, alice.privateKey)
// Or use delegateSignTransaction to provide your own signature function
function signTransaction() {
// get privateKey from somewhere
const privateKeyBuffer = Buffer.from(base58.decode(alice.privateKey))
return function sign(serializedTransaction, input, index) {
const transactionUniqueFulfillment = input.fulfills ? serializedTransaction
.concat(input.fulfills.transaction_id)
.concat(input.fulfills.output_index) : serializedTransaction
const transactionHash = crypto.createHash('sha3-256').update(transactionUniqueFulfillment).digest()
const ed25519Fulfillment = new Ed25519Sha256();
ed25519Fulfillment.sign(transactionHash, privateKeyBuffer);
return ed25519Fulfillment.serializeUri();
};
}
const txSigned = driver.Transaction.delegateSignTransaction(tx, signTransaction())
// Send the transaction off to Planetmint
const conn = new driver.Connection(API_PATH)
conn.postTransactionCommit(txSigned)
.then(retrievedTx => console.log('Transaction', retrievedTx.id, 'successfully posted.'))Browser usage
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Planetmint boilerplate</title>
<!-- Adjust version to your needs -->
<script src="https://unpkg.com/planetmint-driver@0.0.1/dist/browser/planetmint-driver.window.min.js"></script>
<script>
// Planetmint server instance (e.g. https://example.com/api/v1/)
const API_PATH = 'http://localhost:9984/api/v1/'
// Create a new keypair.
const alice = new Planetmint.Ed25519Keypair()
// Construct a transaction payload
const tx = Planetmint.Transaction.makeCreateTransaction(
// Define the asset to store, in this example it is the current temperature
// (in Celsius) for the city of Berlin.
{ city: 'Berlin, DE', temperature: 22, datetime: new Date().toString() },
// Metadata contains information about the transaction itself
// (can be `null` if not needed)
{ what: 'My first Planetmint transaction' },
// A transaction needs an output
[ Planetmint.Transaction.makeOutput(
Planetmint.Transaction.makeEd25519Condition(alice.publicKey))
],
alice.publicKey
)
// Sign the transaction with private keys
const txSigned = Planetmint.Transaction.signTransaction(tx, alice.privateKey)
// Send the transaction off to Planetmint
let conn = new Planetmint.Connection(API_PATH)
conn.postTransactionCommit(txSigned)
.then(res => {
const elem = document.getElementById('lastTransaction')
elem.href = API_PATH + 'transactions/' + txSigned.id
elem.innerText = txSigned.id
console.log('Transaction', txSigned.id, 'accepted')
})
// Check console for the transaction's status
</script>
</head>
<body id="home">
<h1>Hello Planetmint</h1>
<p>Your transaction id is: <a id="lastTransaction" target="_blank"><em>processing</em></a></p>
</body>
</html>Planetmint Documentation
- The Hitchhiker's Guide to BigchainDB
- HTTP API Reference
- The Transaction Model
- Asset Transfer
- All Planetmint Documentation
Speed Optimizations
This implementation plays "safe" by using JS-native (or downgradable) libraries for its crypto-related functions to keep compatibilities with the browser. If you do want some more speed, feel free to explore the following:
- chloride, or its underlying sodium library
- node-sha3 -- MAKE SURE to use steakknife's fork if the FIPS 202 upgrade hasn't been merged (otherwise, you'll run into all kinds of hashing problems)
Development
git clone git@github.com:planetmint/planetmint-driver-ts.git
cd planetmint-driver-ts/
npm i
npm run devAfter updating source files in src/, make sure to update the API documentation. The following command will scan all source files and create the Markdown output into ./API.md:
npm run docRelease Process
See the file named RELEASE_PROCESS.md.
Authors
- Planetmint contact@ipdb.global
- Planetmint contributors
Licenses
See LICENSE and LICENSE-docs.