DAG4 - DAG JavaScript SDK

This is the DAG [JavaScript SDK][docs] for Constellation Network.

Please read the [documentation][docs] for more detailed instructions. The following includes basic install and configuration.

Installation

Node

npm install @stardust-collective/dag4

Yarn

yarn add @stardust-collective/dag4

Usage

Interacting with wallets

Create a private key

const pk = dag4.keyStore.generatePrivateKey();

Login with the private key

dag4.account.loginPrivateKey(pk);

Check DAG address

const address = dag4.account.address;

Connecting to the network

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

// Connect to default network endpoints
dag4.account.connect({
    networkVersion: '2.0',
    testnet: true
})

// Or provide specific configuration
// L0/L1 urls can point to a specific node
dag4.account.connect({
    networkVersion: '2.0',
    beUrl: 'https://be-testnet.constellationnetwork.io',
    l0Url: 'http://13.52.246.74:9000',
    l1Url: 'http://13.52.246.74:9010'
})

Check address balance

// Get an address balance
const balance = await dag4.network.getAddressBalance('DAGabc123...');

Get address last reference

dag4.network.getAddressLastAcceptedTransactionRef('DAGabc123...');

Sending transactions

Dag4.js supports both online and offline transaction signing as well as bulk transaction sending. You must be logged in with a pk and connected to the network to send transactions.

Send a single transaction

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

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

Send bulk transactions

const transfers = [
    {address: 'DAGabc123...', amount: 0.000123, fee: 0},
    {address: 'DAGabc124...', amount: 0.000124, fee: 0},
    {address: 'DAGabc125...', amount: 0.000125, fee: 0},
    {address: 'DAGabc126...', amount: 0.000126, fee: 0},
    {address: 'DAGabc127...', amount: 0.000127, fee: 0},
    {address: 'DAGabc128...', amount: 0.000128, fee: 0.00000001}
];

  const hashes = await dag4.account.transferDagBatch(transfers);

Sign transactions offline, then send online

// First get the last txn reference, this can also be retrieved from an offline source
const lastRef = await dag4.network.getAddressLastAcceptedTransactionRef('DAGWalletSendingAddress');

const transfers = [
    {address: 'DAGabc123...', amount: 0.000123, fee: 0},
    {address: 'DAGabc124...', amount: 0.000124, fee: 0}
];

const txns = await dag4.account.generateBatchTransactions(transfers, lastRef);

// Send online when ready
const hashes = await dag4.account.sendBatchTransactions(txns);

Checking transaction status

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 that the transaction has registered on 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');
  }
}

Upgrading from networkVersion 1.0

v1.2.0 of the dag4 package introduces support for Constellation mainnet 2.0 and a number of new features specific to the new network version. It is also 100% backwards compatible with existing mainnet 1.0 integrations from earlier versions (1.1.x) of the package. Not all endpoints relevant to mainnet 1.0 are used in 2.0 though so there is a migration process to prepare for the switchover in networks.

Migrate all calls to specific APIs to use dag4.network

// Mainnet 1.0
await dag4.network.loadBalancerApi.getAddressLastAcceptedTransactionRef('DAGabc123');

// Mainnet 1.0 and 2.0 support based on configured network version
await dag4.network.getAddressLastAcceptedTransactionRef('DAGabc123');

Use dag4.account as much as possible

// mainnet 1.0
await dag4.keyStore.generateTransaction(...);

// mainnet 1.0 and 2.0 support based on configured network version
await dag4.account.generateSignedTransaction(...);

After the above changes, both versions of the network are supported with a configuration change

// mainnent 1.0 support
dag4.account.connect({
    networkVersion: '1.0'
});

// mainnet 2.0 support
dag4.account.connect({
    networkVersion: '2.0'
});

Documentation

Documentation can be found at [Wiki][docs].

Building

Build the dag4.js package:

npm run build

Testing (mocha)

npm test --workspaces

Community

• Discord
• Constellation Telegram]
• Stardust Telegram]

---

License

This project is licensed under the terms of the MIT license.