Autonomys Auto Consensus SDK

Overview

The Autonomys Auto Consensus SDK (@autonomys/auto-consensus) offers a suite of functions for interacting with the Autonomys Network's consensus layer. It enables developers to:

Manage Accounts: Retrieve account information and balances.
Handle Balances: Check balances and total token issuance.
Perform Transfers: Transfer tokens between accounts.
Stake and Nominate Operators: Participate in staking operations.
Access Blockchain Information: Fetch block numbers, hashes, and network timestamps.
Interact with Domains: Retrieve domain-related data.

Features

Account Management: Access detailed account information, including nonce and balance data.
Balance Operations: Retrieve account balances and the total issuance of tokens in the network.
Token Transfers: Transfer tokens securely between addresses.
Staking Functionality: Register operators, nominate operators, and manage staking operations.
Blockchain Information Access: Fetch current block numbers, block hashes, and network timestamps.
Domain Interactions: Access domain registry information and staking summaries.
TypeScript Support: Fully typed for enhanced developer experience.

Installation

Install the package via npm or yarn:

# Using npm
npm install @autonomys/auto-consensus

# Using yarn
yarn add @autonomys/auto-consensus

Getting Started

Prerequisites

Node.js (version 14 or higher)
TypeScript (optional, but recommended for development)
Familiarity with async/await and promise handling in JavaScript/TypeScript.
@autonomys/auto-utils package installed (as it provides utility functions and API activation).

Importing the SDK

You can import specific functions from the package as needed:

import {
  account,
  balance,
  totalIssuance,
  transfer,
  registerOperator,
  nominateOperator,
  blockNumber,
  blockHash,
  networkTimestamp,
  domains,
  domainStakingSummary,
  latestConfirmedDomainBlock,
} from '@autonomys/auto-consensus'

Usage Examples

Below are examples demonstrating how to use the functions provided by @autonomys/auto-consensus.

1. Account Management

Retrieve Account Information

Get detailed account information, including the nonce and balance data.

import { account } from '@autonomys/auto-consensus'
import { activate } from '@autonomys/auto-utils'
;(async () => {
  const api = await activate({ networkId: 'your_network_id' })
  const accountData = await account(api, 'your_address')

  console.log(`Nonce: ${accountData.nonce}`)
  console.log(`Free Balance: ${accountData.data.free}`)
  console.log(`Reserved Balance: ${accountData.data.reserved}`)

  await api.disconnect()
})()

Parameters:

api (ApiPromise): Connected API instance.
address (string): The account address.

Returns:

An object containing:
- nonce: The account's transaction nonce.
- data: An object with balance details (free, reserved, miscFrozen, feeFrozen).

2. Balance Operations

Retrieve Account Balance

Get the free balance of an account.

import { balance } from '@autonomys/auto-consensus'
import { activate } from '@autonomys/auto-utils'
;(async () => {
  const api = await activate({ networkId: 'your_network_id' })
  const accountBalance = await balance(api, 'your_address')

  console.log(`Free Balance: ${accountBalance.free}`)

  await api.disconnect()
})()

Get Total Issuance

Retrieve the total token issuance in the network.

import { totalIssuance } from '@autonomys/auto-consensus'
;(async () => {
  const total = await totalIssuance('your_network_id')

  console.log(`Total Issuance: ${total.toString()}`)
})()

Parameters:

networkId (string, optional): The network ID.

Returns:

A Codec representing the total issuance value.

3. Transfers

Transfer Tokens

Transfer tokens from one account to another.

import { transfer, events } from '@autonomys/auto-consensus'
import { activate, activateWallet, signAndSendTx, disconnect } from '@autonomys/auto-utils'
;(async () => {
  const api = await activate({ networkId: 'your_network_id' })
  const { accounts } = await activateWallet({
    networkId: 'your_network_id',
    mnemonic: 'your_mnemonic',
  })

  const sender = accounts[0]
  const recipientAddress = 'recipient_address'
  const amount = '1000000000000' // Amount in smallest units (e.g., wei)

  const tx = await transfer(api, recipientAddress, amount)

  // Sign and send the transaction
  await signAndSendTx(sender, tx, [events.transfer])

  console.log(`Transferred ${amount} tokens to ${recipientAddress}`)

  await disconnect(api)
})()

Parameters:

api (ApiPromise): Connected API instance.
recipient (string): Recipient's address.
amount (number | string | BN): Amount to transfer.

Returns:

A SubmittableExtrinsic transaction object.

4. Staking Operations

Register an Operator

import { registerOperator, events } from '@autonomys/auto-consensus'
import { activate, activateWallet, signAndSendTx } from '@autonomys/auto-utils'
;(async () => {
  const api = await activate({ networkId: 'your_network_id' })

  // Sender's account (who will register the operator)
  const { accounts: senderAccounts } = await activateWallet({
    networkId: 'your_network_id',
    mnemonic: 'sender_mnemonic',
  })
  const sender = senderAccounts[0]

  // Operator's account
  const { accounts: operatorAccounts } = await activateWallet({
    networkId: 'your_network_id',
    mnemonic: 'operator_mnemonic',
  })
  const operatorAccount = operatorAccounts[0]

  const tx = await registerOperator({
    api,
    senderAddress: sender.address,
    Operator: operatorAccount,
    domainId: '0', // Domain ID where the operator will be registered
    amountToStake: '1000000000000000000', // Amount in smallest units
    minimumNominatorStake: '10000000000000000',
    nominationTax: '5', // Percentage as a string (e.g., '5' for 5%)
  })

  // Sign and send the transaction
  await signAndSendTx(sender, tx, [events.operatorRegistered])

  console.log('Operator registered successfully')
})()

Parameters:

api (ApiPromise): Connected API instance.
senderAddress (string): Address of the sender registering the operator.
Operator (KeyringPair): Key pair of the operator account.
domainId (string): ID of the domain.
amountToStake (string): Amount to stake in smallest units.
minimumNominatorStake (string): Minimum stake required from nominators.
nominationTax (string): Percentage tax for nominations.

Returns:

A SubmittableExtrinsic transaction object.

Nominate an Operator

Nominate an existing operator by staking tokens.

import { nominateOperator, events } from '@autonomys/auto-consensus'
import { activate, activateWallet, signAndSendTx } from '@autonomys/auto-utils'
;(async () => {
  const api = await activate({ networkId: 'your_network_id' })
  const { accounts } = await activateWallet({
    networkId: 'your_network_id',
    mnemonic: 'nominator_mnemonic',
  })
  const nominator = accounts[0]

  const operatorId = '1' // The ID of the operator to nominate
  const amountToStake = '5000000000000000000' // Amount in smallest units

  const tx = await nominateOperator({
    api,
    operatorId,
    amountToStake,
  })

  // Sign and send the transaction
  await signAndSendTx(nominator, tx, [events.operatorNominated])

  console.log(`Nominated operator ${operatorId} with ${amountToStake} stake`)
})()

Parameters:

api (ApiPromise): Connected API instance.
operatorId (string): ID of the operator to nominate.
amountToStake (string): Amount to stake in smallest units.

Returns:

A SubmittableExtrinsic transaction object.

5. Blockchain Information

Get Block and Network Information

Retrieve the current block number, block hash, and network timestamp.

import { blockNumber, blockHash, networkTimestamp } from '@autonomys/auto-consensus'
;(async () => {
  const currentBlockNumber = await blockNumber()
  const currentBlockHash = await blockHash()
  const currentTimestamp = await networkTimestamp()

  console.log(`Current Block Number: ${currentBlockNumber}`)
  console.log(`Current Block Hash: ${currentBlockHash}`)
  console.log(`Network Timestamp: ${currentTimestamp}`)
})()

Functions:

blockNumber(): Returns the current block number as a BigInt.
blockHash(): Returns the current block hash as a hex string.
networkTimestamp(): Returns the network timestamp as a BigInt.

6. Domain Interactions

Retrieve Domains Information

Get the list of domains registered on the network.

import { domains } from '@autonomys/auto-consensus'
import { activate } from '@autonomys/auto-utils'
;(async () => {
  const api = await activate({ networkId: 'your_network_id' })
  const domainList = await domains(api)

  domainList.forEach((domain) => {
    console.log(`Domain ID: ${domain.id}`)
    console.log(`Owner Address: ${domain.owner}`)
    console.log(`Creation Block: ${domain.creationBlock}`)
    // ...other domain properties
  })

  await api.disconnect()
})()

Get Domain Staking Summary

Retrieve staking summaries for all domains.

import { domainStakingSummary } from '@autonomys/auto-consensus'
import { activate } from '@autonomys/auto-utils'
;(async () => {
  const api = await activate({ networkId: 'your_network_id' })
  const stakingSummaries = await domainStakingSummary(api)

  stakingSummaries.forEach((summary) => {
    console.log(`Domain ID: ${summary.domainId}`)
    console.log(`Total Stake: ${summary.totalStake}`)
    // ...other summary properties
  })

  await api.disconnect()
})()

Get Latest Confirmed Domain Blocks

Fetch the latest confirmed blocks for each domain.

import { latestConfirmedDomainBlock } from '@autonomys/auto-consensus'
import { activate } from '@autonomys/auto-utils'
;(async () => {
  const api = await activate({ networkId: 'your_network_id' })
  const confirmedBlocks = await latestConfirmedDomainBlock(api)

  confirmedBlocks.forEach((blockInfo) => {
    console.log(`Domain ID: ${blockInfo.id}`)
    console.log(`Block Number: ${blockInfo.number}`)
    console.log(`Block Hash: ${blockInfo.hash}`)
    // ...other block properties
  })

  await api.disconnect()
})()

API Reference

Account Functions

`account(api: Api, address: string): Promise<AccountData>`

Retrieve detailed account information.

Parameters:
- api (Api): Connected API instance.
- address (string): The account address.
Returns: Promise<AccountData> containing nonce and data with balance details.

`balance(api: Api, address: string): Promise<BalanceData>`

Get the balance data of an account.

Parameters:
- api (Api): Connected API instance.
- address (string): The account address.
Returns: Promise<BalanceData> with balance details.

Balance Functions

`totalIssuance(networkId?: string): Promise<Codec>`

Retrieve the total token issuance in the network.

Parameters:
- networkId (string, optional): The network ID.
Returns: Promise<Codec> representing the total issuance.

Transfer Functions

`transfer(api: ApiPromise, recipient: string, amount: BN | string | number): SubmittableExtrinsic`

Create a transfer transaction.

Parameters:
- api (ApiPromise): Connected API instance.
- recipient (string): Recipient's address.
- amount (BN | string | number): Amount to transfer.
Returns: SubmittableExtrinsic transaction object.

Staking Functions

`registerOperator(params: RegisterOperatorParams): Promise<SubmittableExtrinsic>`

Parameters:
- params (RegisterOperatorParams): Parameters for operator registration.
Returns: Promise<SubmittableExtrinsic>

`nominateOperator(params: NominateOperatorParams): Promise<SubmittableExtrinsic>`

Nominate an existing operator.

Parameters:
- params (NominateOperatorParams): Parameters for nominating an operator.
Returns: Promise<SubmittableExtrinsic>

Blockchain Information Functions

`blockNumber(): Promise<bigint>`

Get the current block number.

Returns: Promise<bigint>

`blockHash(): Promise<string>`

Get the current block hash.

Returns: Promise<string>

`networkTimestamp(): Promise<bigint>`

Get the network timestamp.

Returns: Promise<bigint>

Domain Functions

`domains(api: Api): Promise<DomainRegistry[]>`

Retrieve the list of domains.

Parameters:
- api (Api): Connected API instance.
Returns: Promise<DomainRegistry[]>

`domainStakingSummary(api: Api): Promise<DomainStakingSummary[]>`

Get staking summaries for domains.

Parameters:
- api (Api): Connected API instance.
Returns: Promise<DomainStakingSummary[]>

`latestConfirmedDomainBlock(api: Api): Promise<ConfirmedDomainBlock[]>`

Fetch the latest confirmed domain blocks.

Parameters:
- api (Api): Connected API instance.
Returns: Promise<ConfirmedDomainBlock[]>

Error Handling

When using @autonomys/auto-consensus, make sure to handle errors, especially when interacting with network operations.

Example:

import { account } from '@autonomys/auto-consensus'
import { activate } from '@autonomys/auto-utils'
;(async () => {
  try {
    const api = await activate({ networkId: 'your_network_id' })
    const accountData = await account(api, 'your_address')

    // Use accountData...

    await api.disconnect()
  } catch (error) {
    console.error('Error occurred:', error)
  }
})()

Contributing

We welcome contributions to @autonomys/auto-consensus! Please follow these guidelines:

Fork the repository on GitHub.

Clone your fork locally:

git clone https://github.com/your-username/auto-sdk.git
cd auto-sdk/packages/auto-consensus

Install dependencies:
```
yarn install
```
Make your changes and ensure all tests pass:
```
yarn test
```
Commit your changes with clear and descriptive messages.
Push to your fork and create a pull request against the main branch of the original repository.

Code Style

Use TypeScript for all code.
Follow the existing coding conventions.
Run yarn lint to ensure code style consistency.

Testing

Add tests for any new features or bug fixes.
Ensure all existing tests pass.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Additional Resources

Autonomys Academy: Learn more at Autonomys Academy.
Auto-Utils Package: Utility functions used alongside auto-consensus can be found in @autonomys/auto-utils.

Contact

If you have any questions or need support, feel free to reach out:

GitHub Issues: GitHub Issues Page

We appreciate your feedback and contributions!