Sign an arbitrary message​

The dag4-keystore package can be used to sign messages using a private key. Messages are signed using secp256k1 which generates a deterministic and canonical ECDSA signature that can be verified with a public key. This example code is not intended to be used to sign transactions.

const privKey = dag4.keyStore.generatePrivateKey();
const pubKey = dag4.keyStore.getPublicKeyFromPrivate(privateKey);

const signature = await dag4.keyStore.sign(privKey, message);

const verified = dag4.keyStore.verify(pubKey, message, signature);

if (verified) {
  console.log('Signature verified');
} else {
  console.log('Signature invalid');
}

Architecture

In order to make the most of Constellation Network APIs, a brief understanding of the architecture of the network is useful. The Hypergraph consists of multiple layers of networks of individual responsibility through which transactions flow. Each of the major network layers has REST API endpoints available with distinct functionality. Transactions are sent to the outermost layer, labeled as L1 networks in the graphic, before being processed into a state snapshot in an L0 layer.

DAG transactions are sent to the DAG L1 network which bundles the transactions into blocks and sends them to the Global L0 for inclusion into global snapshots. Snapshots are then indexed by the Block Explorer via a snapshot streaming service that processes them.

Metagraph token transactions flow in a similar way from the metagraph currency L1 where they're received, bundled into blocks, and then passed to the currency L0 layer to be included in metagraph snapshots. The metagraph snapshots are then submitted to the Global L0 to be included in global snapshots and eventually indexed into the Block Explorer via the snapshot streaming service.

The APIs for each of the L1 and L0 layers is nearly identical with a few minor differences, namely endpoint naming of /dag for DAG endpoints and /currency for currency endpoints. You can explore the API specs for each in the Network APIs sections below.

In summary, the functionalities of the different APIs for DAG and metagraph tokens are as follows:

DAG​

DAG L1​

• DAG transactions are sent to this API via the /transactions POST endpoint.

• Pending transactions can be queried through this API via the /transactions/:hash endpoint.

• The address lastRef for an address can be queried here as well.

Global L0​

• Query global snaphots

• Query DAG supply and address balances

• Submit metagraph (state channel) snapshots

Metagraph Tokens​

Metagraph L1​

• DAG transactions are sent to this API via the /transactions POST endpoint.

• Pending transactions can be queried through this API via the /transactions/:hash endpoint.

• The address lastRef for an address can be queried here as well.

Metagraph L0​

• Query metagraph snapshots

• Query metagraph token supply and address balances

Global L0​

• Submit metagraph (state channel) snapshots

Constellation provides developers with a full featured IntegrationNet to test applications and metagraphs before they're ready for the production environment. The IntegrationNet has all of the same features as MainNet and can therefore be used to validate application integrations in a realistic way.

Connecting to IntegrationNet​

The following urls can used to access IntegrationNet:

• Block Explorer API: https://be-integrationnet.constellationnetwork.io

• Global L0 API: https://l0-lb-integrationnet.constellationnetwork.io

• DAG L1 API: https://l1-lb-integrationnet.constellationnetwork.io

Faucet​

Constellation hosts a IntegrationNet faucet which distributes IntegrationNet DAG for testing purposes. This coin has no value and can only be used on IntegrationNet. The faucet provides small amounts of DAG at each request with rate limiting to prevent depletion of its DAG reserves.

The faucet can be accessed at:

GET https://faucet.constellationnetwork.io/integrationnet/faucet/<YOUR WALLET ADDRESS>

Interacting with Wallets​

A wallet consists of a private key, a public key, and an address. You can create a new private key like this.

const pk = dag4.keyStore.generatePrivateKey();

Copy

Login with a PK​

Before accessing methods on dag4.account specific to a wallet, you'll need to log in with a private key or seed phrase.

dag4.account.loginPrivateKey(pk);

Copy

Login with a seed phrase​

If you already have a pneumonic phrase generated by a web wallet or somewhere else you can log in with that as well.

dag4.account.loginSeedPhrase('disco foxtrot calm appleseed trinity organ putter waldorf ordinary shatter green portion');

Copy

Check DAG address​

const address = dag4.account.address;

Copy

Get wallet public key​

dag4.account.publicKey;

The dag4.js typescript library provides secure wallet functionality in javascript and convenient wrappers for interacting with Constellation Network APIs. The library is platform agnostic and can be used to build apps in browsers, NodeJS, or React Native.

View Dag4.js on Github

You can find the dag4 repo and additional documentation on Github.

Installation​

NPM

npm install @stardust-collective/dag4

or Yarn

yarn add @stardust-collective/dag4

Usage​

Node

const { dag4 } = require('@stardust-collective/dag4');

ES6

import { dag4 } from '@stardust-collective/dag4';

Dag4.js provides reasonable configuration values by default for accessing Constellation Network versions 1.0 and 2.0.

Minimal network configuration​

dag4.account.connect({
  networkVersion: '2.0',
  testnet: true
});

Custom network configuration​

You can provide custom values for each the three network API endpoints to set up a custom connection.

dag4.account.connect({
  networkVersion: '2.0',
  beUrl: 'https://be-mainnet.constellationnetwork.io/',
  l0Url: 'http://13.52.246.74:9000',
  l1Url: 'http://13.52.246.74:9010'
});

Default Endpoints​

The following endpoints are used by default by Dag4.

IntegrationNet​

• Block Explorer API: https://be-integrationnet.constellationnetwork.io

• L0 API: https://l0-lb-integrationnet.constellationnetwork.io

• L1 API: https://l1-lb-integrationnet.constellationnetwork.io

dag4.account.connect({
  id: 'integration2',
  networkVersion: '2.0',
  beUrl: 'https://be-integrationnet.constellationnetwork.io',
  l0Url: 'https://l0-lb-integrationnet.constellationnetwork.io',
  l1Url: 'https://l1-lb-integrationnet.constellationnetwork.io'
}, false);

MainNet​

• Block Explorer API: https://be-mainnet.constellationnetwork.io

• L0 API: https://l0-lb-mainnet.constellationnetwork.io

• L1 API: https://l1-lb-mainnet.constellationnetwork.io

dag4.account.connect({
  networkVersion: '2.0',
  testnet: false
});

TestNet​

• Block Explorer API: https://be-testnet.constellationnetwork.io

• L0 API: https://l0-lb-testnet.constellationnetwork.io

• L1 API: https://l1-lb-testnet.constellationnetwork.io

dag4.account.connect({
  networkVersion: '2.0',
  testnet: true
});

Send a single transaction (online)​

const { dag4 } = require('@stardust-collective/dag4');

dag4.account.connect({
  networkVersion: '2.0',
  testnet: true
});

dag4.account.loginPrivateKey('MY-PRIVATE-KEY');

const toAddress = 'DAGabc123...';
const amount = 25.551;
const fee = 0;

await dag4.account.transferDag(toAddress, amount, fee);

Send a transaction (offline signed)​

// Get last ref online, or else fetch from an offline data store
const lastRef = await dag4.network.getAddressLastAcceptedTransactionRef('DAGWalletSendingAddress');

// Get signed transaction (offline)
const txn = await dag4.account.generateSignedTransaction('DAGabc123...', 25.551, 0, lastRef);

// Send transaction (online)
await dag4.network.postTransaction(txn);

Generate bulk transactions offline and send​

// Get last ref online, or else fetch from an offline data store
let lastRef = await dag4.network.getAddressLastAcceptedTransactionRef('DAGWalletSendingAddress');

// Generate txns offline
const txn_data = [
  {to: 'DAGabc123...', amount: 10, fee: 0},
  {to: 'DAGxyz987...', amount: 25.01, fee: 0},
  {to: 'DAGzzz555...', amount: 1.01, fee: 0},
  {to: 'DAGwww988...', amount: 0.00000001, fee: 0},
];

const hashes = await dag4.account.transferDagBatch(txn_data, lastRef);

// console.log(hashes)

Choosing a Transaction Fee

Transactions without a fee are processed at a maximum of one transaction per global snapshot, or roughly 1 transaction every 5 seconds. In practice this means that almost all transactions do not require a fee unless you need to send a large number of transactions in a short period of time. To send more transactions per snapshot, include a small fee of 0.00000001 DAG with each transaction. Up to 100 transactions per snapshot will be processed if a fee is included.

Check the status of a transaction​

When a transaction is sent to the network and is accepted, the response will return a hash that can be used to monitor the status of the transaction.

The transaction will initially be in a "waiting" state before it's included in a block and sent to a snapshot. While in this state you can check its status with the L1 API. Once processed by the network, the transaction will no longer be found via the L1 API and will be found in the block explorer API. At this point the transaction is considered final.

The following process can be used to confirm a transaction has been processed and reached a successful final state.

// Send transaction
const hash = await dag4.network.postTransaction(txn);

// Keep checking the transaction status until this returns null
const pendingTx = await dag4.network.getPendingTransaction(txHash);

// Check the block explore API
if (pendingTx === null) {
  const confirmedTx = await dag4.network.getTransaction(txHash);

  if (confirmedTx) {
    // Txn is confirmed - from this point the state cannot be changed
    console.log('Transaction confirmed');
  } else {
    // The txn cannot be found on block explorer. It's a good idea to wait several seconds and try again to confirm the txn has actually been dropped
    console.log('Transaction dropped - not confirmed');
  }
}

Metagraph tokens work in much the same way as DAG. They share a common transaction format and API interface. Both DAG and metagraph tokens use DAG addresses for their balance maps so a single public/private keypair can control DAG and metagraph token accounts.

Minimum Version

You will need version 2.1.1 or higher in order to interact with metagraph token networks.

In order to interact with a metagraph token you will need to first need to create a connection to the Hypergraph, then create a metagraph client instance to connect to the metagraph and send transactions.

The example below connects to IntegrationNet. Fill in :metagraph-l0-endpoint, :metagraph-currency-l1-endpoint, and :metagraph-id in the code below with the correct details for the metagraph you are connecting to.

The metagraph client has all the same methods as dag4.account except transferDag becomes transfer and transferDagBatch becomes transferBatch.

Transaction Fees

Note that transaction fees on metagraph networks are paid in the network's metagraph token, not in DAG.

The Hypergraph APIs are the public HTTP APIs hosted on Global L0 and the DAG L1 network nodes. Below you'll find an OpenAPI spec for each of the public network environments. In general, TestNet has the bleeding edge features, IntegrationNet has stable new features, and MainNet has fully released features.

DAG L1 API​

The DAG L1 API is used primarily for sending DAG transactions which are then processed through the Global L0 and are eventually visible on the Block Explorer API after reaching finality.

You can use one of the load balancer endpoints below or connect directly to a network node by IP address and port. You can use the load balancer /cluster/info endpoint to find an active network node to connect to. Connect to the node using http and the configured port, ex: http://18.232.193.183:9010

API Spec​

• TestNet

• IntegrationNet

• MainNet

Base urls​:​

• TestNet: https://l1-lb-testnet.constellationnetwork.io

• IntegrationNet: https://l1-lb-integrationnet.constellationnetwork.io

• MainNet: https://l1-lb-mainnet.constellationnetwork.io

Global L0 API​

The Global L0 API can be used to fetch global snapshot information, view DAG supply and address balances, and submit metagraph snapshots.

You can use one of the load balancer endpoints below or connect directly to a network node by IP address and port. You can use the load balancer /cluster/info endpoint to find a network node. Connect using http and the configured port, ex: http://18.232.193.183:9000.

API Spec​

• TestNet

• IntegrationNet

• MainNet

Base urls​:​

• TestNet: https://l0-lb-testnet.constellationnetwork.io

• IntegrationNet: https://l0-lb-integrationnet.constellationnetwork.io

• MainNet: https://l0-lb-mainnet.constellationnetwork.io

See dag4.js used in production open source codebases.

Want to see your open source project featured here? Submit your project for consideration.

The dag4.js typescript library provides secure wallet functionality in javascript and convenient wrappers for interacting with Constellation Network APIs. The library is platform agnostic and can be used to build apps in browsers, NodeJS, or React Native.

NPM

or Yarn

Node

ES6

An off-network API offering indexed and searchable transactions, snapshots, and block information.

API Spec​

• TestNet

• IntegrationNet

• MainNet

Base urls:​

• TestNet: https://be-testnet.constellationnetwork.io

• IntegrationNet: https://be-integrationnet.constellationnetwork.io

• MainNet: https://be-mainnet.constellationnetwork.io

Metagraph APIs are hosted on any metagraph that adheres to the Metagraph Token Standard or implements a custom data endpoint. The APIs described here are very similar to the Hypergraph APIs described in the previous section. The metagraph APIs consist of the Currency L0 API, Currency L1 API, and the Data L1 API. These APIs are hosted on individual metagraphs which may have their own rate limits or specific configurations required.

Currency L0 API​

The Currency L0 API can be used to fetch metagraph snapshot chain information, view token supply and address balances, and submit metagraph snapshots.

You can connect directly to a network node by IP address and port, or by an endpoint provided to you by the metagraph network.

API Spec​

• TestNet

• IntegrationNet

• MainNet

Currency L1 API​

The Currency L1 API is used primarily for sending metagraph token transactions which are then processed through the Global L0, Currency L0, and Global L0.

You can connect directly to a network node by IP address and port, or by an endpoint provided to you by the metagraph network.

API Spec​

• TestNet

• IntegrationNet

• MainNet

Base urls​​

Base urls or ip addresses will be provided by the metagraph network you wish to connect to.

Data L1 API​

The Global L0 API can be used to fetch global snapshot information, view DAG supply and address balances, and submit metagraph (state channel) snapshots.

You can connect directly to a network node by IP address and port, or by an endpoint provided to you by the metagraph network.

API Spec​

• TestNet

• IntegrationNet

• MainNet

Base urls​​

Base urls or ip addresses will be provided by the metagraph network you wish to connect to.