dash-platform-sdk v1.1.1

This is Javascript SDK for Dash Platform chain that let you make queries, create, and sign state transitions locally and broadcast them into network

It uses an WASM bindings layer to a Dash Platform Protocol to create documents, sign transactions and validate provable query responses.

SDK uses a pre-defined set of seed nodes (public RPC) at the start, and then tries to switch to the latest list of nodes fetched from the Dash network through https://rpc.digitalcash.dev if possible

Currently, only minimal features are included, such as document querying and creation of the documents, and all necessary related functions to do that There is no input validation and error handling implemented yet relying on a happy path, this is going to be fixed in next versions

This library is isomorphic and works in both Node.js and Web browsers without polyfilling

Browser Support

The SDK is isomorphic and works in both Node.js and web browsers without requiring polyfills. When using in browsers, make sure to include the library from CDN or bundle it with your application.

Documentation

https://pshenmic.github.io/dash-platform-sdk/index.html

Quickstart

Install

$ npm install dash-platform-sdk
Copy

Alternatively, you could simply include the library from the CDN:

https://unpkg.com/dash-platform-sdk/dist/main.js

Import

To use the SDK, simply import the library and instantiate an instance of DashPlatformSDK:

// ES6 / EcmaScript
import {DashPlatformSDK} from 'dash-platform-sdk'

// CommonJS
const {DashPlatformSDK} = require('dash-platform-sdk')

const sdk = new DashPlatformSDK({network: 'testnet'})
Copy

Or load it straight from the web page:

<script src="https://unpkg.com/dash-platform-sdk/dist/main.js"></script>
<script>
    const sdk = new DashPlatformSDK({network: 'testnet'})
</script>
Copy

Now you're ready to make queries in the network and push your data!

Register your Data Contract

Before you start storing your data in the decentralized storage, you must provide the schema of your data contract. Very similar to traditional databases, you first define the schema, and then can start inserting data according the format you defined.

https://docs.dash.org/projects/platform/en/stable/docs/protocol-ref/data-contract.html

After you define your application schema, you may proceed to registering your data contract in the network:

const owner = 'GARSAVFMjXx8HpQFaNJMqBV7MBgMK4br5UESsB4S31Ec' // identifier of your identity
const identityNonce = await sdk.identities.getIdentityNonce(owner) // nonce

const schema = {
  note: {
    type: 'object',
    properties: {
      message: { type: 'string', position: 0 }
    },
    additionalProperties: false
  }
}

// Create DataContractWASM instance
const dataContract = await sdk.dataContracts.create(
  ownerIdentifier, 
  identityNonce, 
  schema, 
)

// Turn it into StateTransitionWASM
const stateTransition = await sdk.documents.createStateTransition(dataContract, DataContractTransitionType.Create, identityNonce)

// Broadcast in the network
await sdk.stateTransitions.broadcast(stateTransition)
Copy

Push your data in your Data Contract

After you have your Data Contract deployed in the network, you can start inserting your application data. This is done via creating a document in the network:

const dataContractId = 'GWRSAVFMjXx8HpQFaNJMqBV7MBgMK4br5UESsB4S31Ec'
const ownerId = '9VSMojGcwpFHeWnAZzYxJipFt1t3mb34BWtHt8csizQS'
const documentType = 'note'
const revision = BigInt(1)

const identityContractNonce = await sdk.docuemnts.getIdentityContractNonce(ownerId, dataContractId) // nonce

const data = {
    "message": "Hello world!",
}

// Create DocumentWASM instance
const document = await sdk.documents.create(dataContractId, documentType, data, ownerId, revision)

// Turn it into StateTransitionWASM
const stateTransition = await sdk.documents.createStateTransition(dataContract, DataContractTransitionType.Create, identityContractNonce)

// Broadcast transaction
await sdk.stateTransitions.broadcast(stateTransition)
Copy

Update the document

It is possible to update your document if you wish to change the data in your document. This is done by creating a Document Replace Transition in the network:

const dataContractId = 'GWRSAVFMjXx8HpQFaNJMqBV7MBgMK4br5UESsB4S31Ec'
const ownerId = '9VSMojGcwpFHeWnAZzYxJipFt1t3mb34BWtHt8csizQS'
const documentType = 'note'

// Get DocumentWASM from the network
const [document] = await sdk.documents.query(
  dataContractId,
  documentType,
  [['ownerId', '==', ownerId]], // or any other query
)

// Get last identity contract nonce
const identityContractNonce = await sdk.documents.query(ownerId, dataContractId) // nonce

// Turn it into StateTransitionWASM
const stateTransition = await sdk.documents.createStateTransition(document, BatchType.Replace, identityContractNonce + 1n)

// Broadcast transaction
await sdk.stateTransitions.broadcast(stateTransition)
Copy

Delete the document

You can delete the document from the state, and it will not be longer available to query from DAPI.

const dataContractId = 'GWRSAVFMjXx8HpQFaNJMqBV7MBgMK4br5UESsB4S31Ec'
const ownerId = '9VSMojGcwpFHeWnAZzYxJipFt1t3mb34BWtHt8csizQS'
const documentType = 'note'
const revision = BigInt(1)

const identityContractNonce = await sdk.docuemnts.getIdentityContractNonce(ownerId, dataContractId) // nonce

const data = {
    "message": "Hello world!",
}

// Create DocumentWASM instance
const document = await sdk.documents.create(dataContractId, documentType, data, ownerId, revision)

// Turn it into StateTransitionWASM
const stateTransition = await sdk.documents.createStateTransition(dataContract, DataContractTransitionType.Create, identityContractNonce)

// Broadcast transaction
await sdk.stateTransitions.broadcast(stateTransition)
Copy

API Documentation

The full API documentation autogenerated by typedoc is available at GitHub Pages

https://pshenmic.github.io/dash-platform-sdk/index.html

Data Contracts

Get Data Contract By Identifier

Queries a DAPI for data contract and returns a DataContractWASM instance

const dataContractIdentifier = 'GWRSAVFMjXx8HpQFaNJMqBV7MBgMK4br5UESsB4S31Ec'

const dataContract = await sdk.dataContracts.getByIdentifier(dataContractIdentifier)
Copy

Create Data Contract

Create data contract from schema

const ownerIdentifier = 'GARSAVFMjXx8HpQFaNJMqBV7MBgMK4br5UESsB4S31Ec'
const identityNonce = BigInt(11)

const definitions = {
  def1: true
}
const schema = {
  note: {
    type: 'object',
    properties: {
      author: { type: 'string', position: 1 },
      message: { type: 'string', position: 0 }
    },
    additionalProperties: false
  }
}

const config = {
  $format_version: '0',
  canBeDeleted: true,
  readonly: false,
  keepsHistory: false,
  documentsKeepHistoryContractDefault: false,
  documentsMutableContractDefault: true,
  documentsCanBeDeletedContractDefault: true,
  requiresIdentityEncryptionBoundedKey: null,
  requiresIdentityDecryptionBoundedKey: null
}

// Optional: tokenConfiguration for creating token-based contracts
const tokenConfiguration = {
  // token configuration properties
}

const dataContract = await sdk.dataContracts.create(
  ownerIdentifier, 
  identityNonce, 
  schema, 
  definitions, 
  true, // fullValidation 
  tokenConfiguration, // optional
  config,
)
Copy

Data Contract Create Transition

Create Data Contract Create Transition

import { DataContractTransitionType } from 'dash-platform-sdk'

const dataContract = // ... created data contract
const identityNonce = BigInt(1)

const transition = await sdk.dataContracts.createStateTransition(
  dataContract, 
  DataContractTransitionType.Create, 
  identityNonce
)
Copy

Data Contract Update Transition

Create Data Contract Update Transition

import { DataContractTransitionType } from 'dash-platform-sdk'

const dataContract = // ... existing data contract with updates
const identityNonce = BigInt(2)

const transition = await sdk.dataContracts.createStateTransition(
  dataContract, 
  DataContractTransitionType.Update, 
  identityNonce
)
Copy

Documents

Create Document

Creates a DocumentWASM instance that can be used for a state transition creation

const dataContractId = 'GWRSAVFMjXx8HpQFaNJMqBV7MBgMK4br5UESsB4S31Ec'
const ownerId = '9VSMojGcwpFHeWnAZzYxJipFt1t3mb34BWtHt8csizQS'
const documentType = 'domain'
const data = {
  "label": "mydomain",
  "normalizedLabel": "mydomain",
  "normalizedParentDomainName": "dash",
  "records": {
    "dashUniqueIdentityId": ownerId
  }
}
const revision = BigInt(1) // optional, defaults to 1

const document = await sdk.documents.create(dataContractId, documentType, data, ownerId, revision)

console.log(document)
Copy

Query Documents

Performs a query for documents and returns an array of DocumentWASM instances

const dataContractId = 'GWRSAVFMjXx8HpQFaNJMqBV7MBgMK4br5UESsB4S31Ec'
const documentType = 'domain'
const limit = 100
const where =  [['$ownerId', '==', ownerId]]
const orderBy = [['$createdAt', 'desc']]

// optional: pagination options (use only one)
const startAt = document.id // for pagination
const startAfter = document.id // for pagination

const documents = await sdk.documents.query(
  dataContractId, 
  documentType, 
  where, 
  orderBy, 
  limit, 
  startAt, 
  startAfter
)

console.log(documents)
Copy

Document State Transitions

Create Document State Transitions

This method allows creation of various document state transitions using BatchType enum

import { BatchType } from 'dash-platform-sdk'

const document = // ... created or fetched document
const identityContractNonce = BigInt(1)

// Create transition
const createTransition = await sdk.documents.createStateTransition(
  document, 
  BatchType.Create, 
  identityContractNonce
)

// Replace transition
const replaceTransition = await sdk.documents.createStateTransition(
  document, 
  BatchType.Replace, 
  identityContractNonce
)

// Delete transition
const deleteTransition = await sdk.documents.createStateTransition(
  document, 
  BatchType.Delete, 
  identityContractNonce
)

// Purchase transition (requires price parameter)
const purchaseTransition = await sdk.documents.createStateTransition(
  document, 
  BatchType.Purchase, 
  identityContractNonce,
  { price: BigInt(100) }
)

// Transfer transition (requires recipient parameter)
const transferTransition = await sdk.documents.createStateTransition(
  document, 
  BatchType.Transfer, 
  identityContractNonce,
  { recipient: '8VSMojGcwpFHeWnAZzYxJipFt1t3mb34BWtHt8csizQS' }
)

// Update price transition (requires price parameter)
const updatePriceTransition = await sdk.documents.createStateTransition(
  document, 
  BatchType.UpdatePrice, 
  identityContractNonce,
  { price: BigInt(200) }
)
Copy

Identities

Get identity by identifier

Searches an identity by identifier (base58) and returns an IdentityWASM instance

const identifier = 'QMfCRPcjXoTnZa9sA9JR2KWgGxZXMRJ4akgS3Uia1Qv'

const identity = await sdk.identities.getIdentityByIdentifier(identifier)

console.log(identity)
Copy

Get identity by public key hash

const publicKeyHash = 'deadbeefdeadbeefdeadbeefdeadbeefdeadbeef'

const identity = await sdk.identities.getIdentityByPublicKeyHash(publicKeyHash)

console.log(identity)
Copy

Get identity balance

Returns the current balance in credits for a given Identity

const identifier = 'QMfCRPcjXoTnZa9sA9JR2KWgGxZXMRJ4akgS3Uia1Qv'

const balance = await sdk.identities.getIdentityBalance(identifier)

console.log(balance) // BigInt value in credits
Copy

Get identity nonce

Returns a current BigInt identity nonce for a given Identity

const identifier = 'QMfCRPcjXoTnZa9sA9JR2KWgGxZXMRJ4akgS3Uia1Qv'

const identityNonce = await sdk.identities.getIdentityNonce(identifier)

console.log(identityNonce)
Copy

Get identity contract nonce

Returns a current BigInt identity contract nonce for a given Identity and Data Contract

const identifier = 'QMfCRPcjXoTnZa9sA9JR2KWgGxZXMRJ4akgS3Uia1Qv'
const dataContractId = 'GWRSAVFMjXx8HpQFaNJMqBV7MBgMK4br5UESsB4S31Ec'

const identityContractNonce = await sdk.identities.getIdentityContractNonce(identifier, dataContractId)

console.log(identityContractNonce)
Copy

Get identity public keys

Return an array of IdentityPublicKeyWASM for a given identity if found

const identifier = 'QMfCRPcjXoTnZa9sA9JR2KWgGxZXMRJ4akgS3Uia1Qv'

const identityPublicKeys = await sdk.identities.getIdentityPublicKeys(identifier)

console.log(identityPublicKeys)
Copy

State Transition

Broadcast state transition

Broadcasts your state transition in the Dash Platform network

const stateTransition = // ... created state transition

await sdk.stateTransitions.broadcast(stateTransition)
Copy

Wait for state transition result

Waits for an execution of a state transition in the network

const stateTransition = // ... created state transition

await sdk.stateTransitions.waitForStateTransitionResult(stateTransition)
Copy

DPNS Names

Search domain by name (ex. xyz.dash)

const [document] = await sdk.names.search('xyz.dash')

console.log(document)
Copy

Node Status

Returns status of the node and protocol info

const status = await sdk.node.status()

console.log(status.chain.latestBlockHash)
console.log(status.time.epoch)
Copy

Utils

Base58 encoding/decoding

// Base58 to bytes
const base58String = 'GWRSAVFMjXx8HpQFaNJMqBV7MBgMK4br5UESsB4S31Ec'
const bytes = sdk.utils.base58ToBytes(base58String)

// Bytes to Base58
const base58 = sdk.utils.bytesToBase58(bytes)
Copy

Hex encoding/decoding

// Hex to bytes
const hexString = 'deadbeef'
const bytes = sdk.utils.hexToBytes(hexString)

// Bytes to hex
const hex = sdk.utils.bytesToHex(bytes)
Copy

Convert to homograph safe chars

Converts a string to homograph-safe characters for DPNS names

const str = 'alice'
const normalizedString = sdk.utils.convertToHomographSafeChars(str) // al1ce
Copy

NodeStatus

Comprehensive node status information including version, chain, network, and time data.

Error Handling

The SDK currently relies on a happy path and doesn't include comprehensive error handling. This will be improved in future versions. For now, wrap SDK calls in try-catch blocks:

try {
  const identity = await sdk.identities.getIdentityByIdentifier('invalid-id')
} catch (error) {
  console.error('Failed to fetch identity:', error)
}
Copy