Skip to main content

Utils

Auto-Utils Package Documentation​

Introduction​

The @autonomys/auto-utils package provides core utility functions for interacting with the Autonomys Network. It offers functionalities for:

  • Wallet Management: Initialize and manage wallets using mnemonics or URIs.
  • Network Configuration: Access and manage network and domain settings.
  • Data Storage: Save and read data to and from local storage or the file system.
  • Cryptographic Operations: Perform hashing and data manipulation using cryptographic functions.
  • API Activation: Activate and manage connections to the Autonomys Network APIs.
  • Address Utilities: Convert and decode addresses to and from standardized formats.

This package serves as the foundational layer for building applications within the Autonomys ecosystem.

Installation​

Install the package via npm or yarn:

# Using npm
npm install @autonomys/auto-utils

# Using yarn
yarn add @autonomys/auto-utils

Importing the Package​

Before using the functions provided by the auto-utils package, you need to import them into your project:

// Import specific functions
import { activateWallet, activate, blake2b_256 } from '@autonomys/auto-utils';

// Or import everything
import * as utils from '@autonomys/auto-utils';

Available Functions​

Account Utilities​

  • createAccountIdType(api, address): Uint8Array: Creates an AccountId object from an address.

Event Utilities​

  • Type: Enum for event types (e.g., system).
  • eventName(type, event): string: Combines type and event to a full event name.
  • eventsGroup: Groups system events by name.
  • expectSuccessfulTxEvent: Default success event names array.

Transaction Utilities​

  • signAndSendTx(sender, tx, options?, eventsExpected?, log?, mapErrorCodeToEnum?): Promise<TransactionSignedAndSend>: Signs, sends, and validates a transaction.

Signing Utilities​

  • signMessage(signer, address, data): Promise<{ signature: string }>: Signs a message with a signer and address.
  • signingKey(publicKey): string: Converts a public key to a hex string.
  • signatureVerify: Verifies signatures (re-exported from @polkadot/util-crypto).

Event Validation​

  • validateEvents(events, eventsExpected?, tx, block, log?): EventsValidated: Checks if expected events are in transaction events.

Utility Functions​

  • isAddress(address): boolean: Validates a Substrate address.
  • isHex(value): boolean: Validates a hexadecimal string.

Wallet Management​

  • activate(options?): Promise<ApiPromise>: Connects to the Autonomys Network.
  • activateWallet(options): Promise<{ api, accounts }>: Activates a wallet using mnemonic or URI.
  • mockWallets(options, api?): Promise<Wallet[]>: Creates mock wallets for testing.
  • getMockWallet(name, wallets): Wallet: Retrieves a mock wallet by name.

Network Management​

  • networks: Array of available networks.
  • getNetworkDetails(options): NetworkDetails: Gets details of a network.
  • getNetworkDomainDetails(options): DomainDetails: Gets details of a domain.

Cryptographic Functions​

  • blake2b_256(data): string: Hashes data with BLAKE2b-256.
  • stringToUint8Array(string): Uint8Array: Converts a string to Uint8Array.
  • concatenateUint8Arrays(...arrays): Uint8Array: Concatenates multiple Uint8Arrays.

Data Storage​

  • save(key, value): void: Saves data locally.
  • read(key): any: Reads data from local storage.

Address Utilities​

  • address(input): string: Standardizes an address format.
  • decode(input): Uint8Array: Decodes an address to bytes.

Note: All asynchronous functions return a Promise and should be used with await for proper execution flow.

Usage Examples​

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

1. Wallet Management​

Activate a Wallet​

Activate a wallet using a mnemonic phrase:

import { activateWallet } from '@autonomys/auto-utils';

(async () => {
  const mnemonic = 'your mnemonic phrase here';

  const { api, accounts } = await activateWallet({
    mnemonic,
    networkId: 'gemini-3h', // Optional: specify the network ID
  });

  const account = accounts[0];
  console.log(`Connected with account address: ${account.address}`);

  // Perform actions with the account...

  // Disconnect when done
  await api.disconnect();
})();

Activate a Wallet Using URI​

Activate a wallet using a URI:

import { activateWallet } from '@autonomys/auto-utils';

(async () => {
  const { api, accounts } = await activateWallet({
    uri: '//Alice',
    networkId: 'localhost', // Connect to a local network
  });

  const account = accounts[0];
  console.log(`Connected with account address: ${account.address}`);

  // Disconnect when done
  await api.disconnect();
})();

Create Mock Wallets for Testing​

Create mock wallets for testing purposes:

import { activate, mockWallets, getMockWallet } from '@autonomys/auto-utils';

(async () => {
  const api = await activate({ networkId: 'gemini-3h' });

  const wallets = await mockWallets({}, api);
  const aliceWallet = getMockWallet('Alice', wallets);
  const bobWallet = getMockWallet('Bob', wallets);

  console.log(`Alice's address: ${aliceWallet.accounts[0].address}`);
  console.log(`Bob's address: ${bobWallet.accounts[0].address}`);

  // Disconnect when done
  await api.disconnect();
})();

2. Network Management​

Get Available Networks​

List all available networks:

import { networks } from '@autonomys/auto-utils';

networks.forEach((network) => {
  console.log(`Network ID: ${network.id}, Name: ${network.name}`);
});

Get Network Details​

Retrieve details of a specific network:

import { getNetworkDetails } from '@autonomys/auto-utils';

const network = getNetworkDetails({ networkId: 'gemini-3h' });
console.log(`Network Name: ${network.name}`);
console.log(`RPC URLs: ${network.rpcUrls.join(', ')}`);

Get Domain Details​

Retrieve details of a specific domain within a network:

import { getNetworkDomainDetails } from '@autonomys/auto-utils';

const domain = getNetworkDomainDetails({ domainId: '1', networkId: 'gemini-3h' });
console.log(`Domain Name: ${domain.name}`);
console.log(`RPC URLs: ${domain.rpcUrls.join(', ')}`);

3. Cryptographic Functions​

Hash Data Using BLAKE2b-256​

Hash a string using BLAKE2b-256:

import { blake2b_256, stringToUint8Array } from '@autonomys/auto-utils';

const data = 'Hello, Autonomys!';
const dataBytes = stringToUint8Array(data);
const hash = blake2b_256(dataBytes);

console.log(`Hash: ${hash}`); // Outputs the hash of the input string

Convert String to Uint8Array​

Convert a string to a Uint8Array:

import { stringToUint8Array } from '@autonomys/auto-utils';

const text = 'Sample text';
const byteArray = stringToUint8Array(text);

console.log(byteArray); // Outputs Uint8Array representation of the string

Concatenate Uint8Arrays​

Concatenate two Uint8Array instances:

import { stringToUint8Array, concatenateUint8Arrays } from '@autonomys/auto-utils';

const array1 = stringToUint8Array('First part ');
const array2 = stringToUint8Array('Second part');

const concatenated = concatenateUint8Arrays(array1, array2);
console.log(`Concatenated Result: ${new TextDecoder().decode(concatenated)}`);
// Outputs: "First part Second part"

4. API Activation​

Activate the Network API​

Connect to the Autonomys Network:

import { activate } from '@autonomys/auto-utils';

(async () => {
  const api = await activate({ networkId: 'gemini-3h' });

  console.log('API connected');

  // Perform API calls...

  // Disconnect when done
  await api.disconnect();
})();

Activate a Domain API​

Connect to a specific domain within the network:

import { activateDomain } from '@autonomys/auto-utils';

(async () => {
  const api = await activateDomain({ domainId: '1', networkId: 'gemini-3h' });

  console.log('Domain API connected');

  // Perform domain-specific API calls...

  // Disconnect when done
  await api.disconnect();
})();

5. Data Storage​

Save and Read Data​

Save data to local storage or the file system and read it back:

import { save, read } from '@autonomys/auto-utils';

const key = 'myData';
const value = { message: 'Hello, Autonomys!' };

// Save data
save(key, value);

// Read data
const retrievedValue = read(key);
console.log(retrievedValue); // Outputs: { message: 'Hello, Autonomys!' }

6. Address Utilities​

Convert Address Formats​

Convert an address to a standardized format and decode it:

import { address, decode } from '@autonomys/auto-utils';

const originalAddress = '5GmS1wtCfR4tK5SSgnZbVT4kYw5W8NmxmijcsxCQE6oLW6A8';
const standardizedAddress = address(originalAddress);
const decodedAddress = decode(originalAddress);

console.log(`Standardized Address: ${standardizedAddress}`);
console.log('Decoded Address:', decodedAddress);

Note: All asynchronous functions return a Promise and should be used with await for proper execution flow.

Notes​

  • Asynchronous Functions: Use await with all promises for proper execution flow.
  • API Disconnection: Always disconnect the API instance after operations to free up resources.
  • Error Handling: Wrap asynchronous calls in try...catch blocks to handle potential errors gracefully.
  • Security Considerations:
    • Private Keys: Handle private keys securely. Do not expose them in code or logs.
    • Data Persistence: Be cautious when saving sensitive data using save and read.