Utils
Auto-Utils Package Documentation
Введение
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 anAccountId
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 toUint8Array
.concatenateUint8Arrays(...arrays): Uint8Array
: Concatenates multipleUint8Array
s.
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
andread
.