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:

• Global L0 API:

• DAG L1 API:

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:

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 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

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

API Spec​

• TestNet

• IntegrationNet

Base urls:

• TestNet:

• IntegrationNet:

• MainNet:

Interacting with Wallets

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.

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:

API Spec

Base urls​:

• TestNet:

• IntegrationNet:

• MainNet:

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: .

API Spec

Base urls​:

• TestNet:

• IntegrationNet:

• MainNet:

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.

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

Usage

Node

ES6

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

Minimal network configuration

Send a single transaction (online)

Send a transaction (offline signed)

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 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.

This document describes how to manually sign transactions on the Constellation Network. Understanding the transaction signing process is crucial for developers implementing custom signing solutions in various programming languages or integrating with the Constellation Network.

Overview

Constellation Network supports two distinct methods for transaction signing:

1. DAG/L0 Token Transactions: Uses Kryo serialization without compression

2. Other Transaction Types: Uses Brotli compression for serialization (TokenLock, AllowSpend, DelegatedStake, etc.)

In the long term, DAG and L0 token transactions will likely be migrated to use the same brotli compression as the newer transaction types but for now, the Kryo serialization method is maintained for backwards compatibility.

Transaction Format

All transactions in the Constellation Network, regardless of type, are submitted to the network using a standard format:

Key components of this format:

• value: Contains the transaction body with all relevant transaction details

• proofs: An array of signatures that validate the transaction

  • Currently, all transactions require exactly one proof in the array

The different transaction signing methods described in this document ultimately produce transaction data in this standard format, though the specific contents of the value field and the method of generating the signature in the proofs array will differ based on the transaction type.

Prerequisites

To sign transactions, you need:

• A private key

• A public key

• Transaction details to be signed

• Understanding of cryptographic operations: SHA-256, SHA-512, and secp256k1 ECDSA signing

1. DAG/L0 Token Transaction Signing

DAG or L0 token transactions follow this signing process:

1.1 Transaction Structure

For token transactions, the following fields are required:

• source: Sender address

• destination: Recipient address

• amount: Transaction amount (in smallest unit, e.g., 1 DAG = 100,000,000 units)

1.2 Transaction Preparation

1. Create a transaction object with the required fields

2. Format the transaction according to the network's expected structure (v2 format)

3. Encode the transaction into a specific format that concatenates fields with their lengths

1.3 Kryo Serialization

The encoded transaction is serialized using Kryo serialization, which follows these steps:

1. Create a prefix using the format: 03 (fixed) + UTF-8 encoded length

2. Convert the encoded transaction to UTF-8 bytes

3. Convert the UTF-8 bytes to hexadecimal format

Example pseudo-code for Kryo serialization:

The UTF-8 encoded length is variable-length encoded with specific bit patterns:

• Bit 8 denotes UTF-8

• Bit 7 denotes if another byte is present

1.4 Hash Computation

Compute the SHA-256 hash of the Kryo-serialized transaction bytes:

1.5 Signature Generation

Sign the hash using ECDSA with the secp256k1 curve and the private key:

1. Compute SHA-512 hash of the transaction hash

2. Sign the SHA-512 hash with the private key using secp256k1 ECDSA

3. Format the signature according to the expected format (often DER encoded and converted to hexadecimal)

1.6 Verification (Optional)

To verify the signature:

1. Use the public key to verify the signature against the same SHA-512 hash

2. Ensure the signature verification passes

2. Other Transaction Types (TokenLock, AllowSpend, DelegatedStake, etc.)

For other transaction types, the signing process uses Brotli compression:

2.1 Transaction Normalization

Before serialization, normalize the transaction object:

1. Sort object keys alphabetically

2. Remove null/undefined values

3. Convert the object to a consistent format

2.2 Brotli Serialization

Serialize the normalized transaction using Brotli compression:

1. Convert the normalized JSON to a string

2. Encode the string as UTF-8 bytes

3. Compress the bytes using Brotli compression (typically with compression level 2)

2.3 Hash Computation

Compute the SHA-256 hash of the Brotli-compressed data:

2.4 Signature Generation

Sign the hash with the private key:

1. Compute SHA-512 hash of the message hash

2. Sign the SHA-512 hash with the private key using secp256k1 ECDSA

3. Format the signature according to the expected format

2.5 Result

The final result should be structured as:

Implementation Considerations

Key Format

• Private keys should be in hexadecimal format without the "0x" prefix

• Public keys for verification can be in compressed or uncompressed format

• When using uncompressed public keys, they may need the "04" prefix

Transaction Amounts

• Transaction amounts and fees should be represented in the smallest unit (datum)

• Example: 1 DAG = 100,000,000 datum (8 decimal places)

• Amounts should be integers after being multiplied by 10^8

Hash Functions

• SHA-256 and SHA-512 implementations should follow the standard specifications

• Input to hash functions should be byte arrays, not hexadecimal strings

ECDSA Signing

• Use secp256k1 curve for ECDSA signing

• Sign the SHA-512 hash of the message, not the message directly

• DER encoding is commonly used for the signature format

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.

Connecting to a metagraph​

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.

Metagraph connection details

A list of existing metagraphs can be found on the . On each metagraph's page you'll find the Metagraph ID, as well as L0 and currency L1 endpoints, which are necessary for configuring your metagraph client to connect to a specific metagraph network.

Send a single transaction

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

Generate bulk transactions offline and send

Transaction Fees

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

Delegated Staking Integration Guide

This guide walks you through integrating with Constellation Network’s Delegated Staking system, including how to create, update, and withdraw delegated stakes for users that want to automate this process through the network APIs.

Delegated staking allows users to lock their tokens on the network and delegate them to a node operator, receiving a share of the validator’s rewards in return. The process relies on TokenLocks and is managed via the Global L0 (gL0) and DAG L1 (dagL1) APIs.

Manual staking using Stargazer Wallet is supported through the website.

API Reference Summary

Before getting started, familiarize yourself with the following endpoints. Note that you'll be interacting with API endpoints on both the and APIs.

Transaction Signing

All POST and PUT requests below follow the brotli compressed signing scheme described in . If using a library like to generate and send requests to the network, serialization and signing will be handled for you automatically. If sending requests directly to the REST APIs without using a library, you will need to generate the signatures manually.

Creating a Delegated Stake

To create a delegated stake, follow these steps:

1. Discover Available Nodes

Use the following API call to list the nodes currently accepting delegated stakes:

Each node record includes:

• nodeId: used to delegate

• name: name provided by the operator

• description: description provided by the operator

You’ll use the nodeId from this list when creating your stake.

2. Fetch TokenLock Parent Reference

Before creating a TokenLock, you need the last reference for your wallet address:

This value will be used as the parentReference in your new TokenLock transaction.

3. Create the TokenLock

Submit a TokenLock to lock your tokens:

• source: set to the address of the wallet sending the request

• amount: number of tokens to lock (in smallest unit, i.e., datum)

• fee: set to zero

4. Fetch DelegatedStake Parent Reference

Now fetch your DelegatedStake's last reference:

Use the returned value as parent when submitting the new stake.

5. Submit Delegated Stake Request

Now that you have your tokenLockRef and parent reference, submit the stake:

Request body includes:

• nodeId: from /node-params

• amount: must exactly match the amount of the TokenLock referenced

• fee

If successful, a hash of the DelegatedStake record will be returned.

6. Verify Stake Activation

Use:

Check that your stake is listed in the activeDelegatedStakes array, and that rewardsAmount is increasing.

Updating a Delegated Stake

Delegated stakes can be redirected to a new node without withdrawal or penalty.

1. Pick a New Node

Re-run:

Choose a new node ID to delegate to.

2. Re-submit the DelegatedStake

Use the same tokenLockRef and stake amount, but change the nodeId.

This will update the position to the new node without incurring a withdrawal penalty. All fields other than nodeId must remain the same as the original request.

3. Confirm the Update

Use:

Ensure the nodeId has updated and rewardAmount continues to increase.

Withdrawing a Delegated Stake

To withdraw a delegated stake (unlock your tokens and receive rewards), follow this process:

1. Submit Withdrawal Request

You’ll need:

• Reference to the original DelegatedStake position

This will start the 21-day unbonding period.

2. Verify Pending Status

After submitting, verify the stake has moved to pendingWithdrawals:

During this time:

• The position no longer accrues rewards

• Tokens remain locked

3. Wait and Confirm Completion

After ~21 days (estimated in network epochProgress), check your wallet:

• TokenLock should be removed

• Rewards should be distributed in a reward transaction