# util

Utility functions for CESS SDK

## Installation

```bash
npm install @cessnetwork/util
```

## Overview

The `@cessnetwork/util` package provides a comprehensive set of utility functions for working with the CESS (Cumulus Encrypted Storage System) network. This package includes utilities for:

* Account management and address validation
* Cryptographic operations and signing
* File hashing and integrity verification
* Network operations
* Data formatting and conversion
* Error handling

## Core Modules

### Account Utilities

Functions for managing CESS accounts, validating addresses, and converting between different formats.

```typescript
import {
    parsePublicKey,
    validateAddress,
    convertAddressFormat,
    encodePublicKeyAsTestNetAddr,
    encodePublicKeyAsMainNetAddr,
    convertAddrToMainNet,
    convertAddrToTestNet,
    evmAddrToCessAddr
} from '@cessnetwork/util';

// Parse a public key from an address
const publicKey = parsePublicKey('cXabc123...');
console.log(publicKey);

// Validate an address
const isValid = validateAddress('cXabc123...');
console.log(isValid);

// Validate an address with specific SS58 format
const isValidTestnet = validateAddress('cXabc123...', 11330);
console.log(isValidTestnet);

// Convert address format
const converted = convertAddressFormat('cXabc123...', 11331);
console.log(converted);

// Convert testnet address to mainnet
const mainnetAddr = convertAddrToMainNet('cXabc123...');
console.log(mainnetAddr);

// Convert mainnet address to testnet
const testnetAddr = convertAddrToTestNet('ceabc123...');
console.log(testnetAddr);

// Convert Ethereum address to CESS address
const cessAddr = evmAddrToCessAddr('0x742d35Cc6634C0532925a3b844Bc454e4438f44e', 11331);
console.log(cessAddr);
```

### Signing Utilities

Functions for signing messages and verifying signatures using mnemonics and cryptographic keys.

```typescript
import {
    sr25519SignWithMnemonic,
    verifySignature,
    safeSignUnixTime,
    parseEvmAccFromEvmSign,
    getWrappedMsg
} from '@cessnetwork/util';

// Sign a message with mnemonic using SR25519
const mnemonic = 'your twelve word mnemonic phrase here';
const signature = sr25519SignWithMnemonic(mnemonic, 'Hello, CESS!');
console.log(signature);

// Verify a signature
const isValid = verifySignature('Hello, CESS!', signature, 'ceabc123...');
console.log(isValid);

// Sign current unix time for gateway requests (as used in gateway operations)
const unixTime = Date.now().toString();
const wrappedMsg = getWrappedMsg(unixTime);
const gatewaySignature = safeSignUnixTime(unixTime, mnemonic);
console.log(gatewaySignature);

// Parse Ethereum account from Ethereum signature
const ethAddress = parseEvmAccFromEvmSign('Hello, CESS!', '0x...signature...');
console.log(ethAddress);
```

### Hash Utilities

Functions for calculating file and data hashes.

```typescript
import { calcSHA256, calcPathSHA256 } from '@cessnetwork/util';

// Calculate SHA256 hash of a buffer
const buffer = Buffer.from('Hello, CESS!');
const hash = calcSHA256(buffer);
console.log(hash);

// Calculate SHA256 hash of a file
const fileHash = await calcPathSHA256('/path/to/file');
console.log(fileHash);
```

## API Reference

### Account Functions

* `parsePublicKey(address: string): Uint8Array` - Parse public key from address
* `encodePublicKeyAsTestNetAddr(publicKey: Uint8Array): string` - Encode public key as testnet address (ss58Format: 11330)
* `encodePublicKeyAsMainNetAddr(publicKey: Uint8Array): string` - Encode public key as mainnet address (ss58Format: 11331)
* `validateAddress(address: string, ss58Format?: number): boolean` - Validate address with optional ss58Format check
* `convertAddressFormat(address: string, targetSs58Format: number): string` - Convert address to specified ss58Format
* `convertAddrToMainNet(address: string): string` - Convert address from ss58Format 11330 to 11331 (cX... -> ce...)
* `convertAddrToTestNet(address: string): string` - Convert address from ss58Format 11331 to 11330 (ce... -> cX...)
* `evmAddrToCessAddr(evmAddr: string, targetSs58Format: number): string` - Convert Ethereum address to CESS address with specified ss58Format

### Signing Functions

* `safeSignUnixTime(unixTime: string | number, mnemonic: string): Uint8Array` - Sign a current unix time with a mnemonic using SR25519
* `getWrappedMsg(unixTime: string | number): Uint8Array` - Wrap a unix time message with tags
* `sr25519SignWithMnemonic(mnemonic: string, msg: string): Uint8Array` - Sign a message with a mnemonic using SR25519
* `verifySignature(msg: string | Uint8Array, sign: Uint8Array, account: string): boolean` - Verify a signature with a public key
* `parseEvmAccFromEvmSign(message: string, sign: string): string` - Parse Ethereum account from Ethereum signature

### Hash Functions

* `calcSHA256(data: Buffer): string` - Calculate SHA256 hash of buffer data
* `calcPathSHA256(filePath: string): Promise<string>` - Calculate SHA256 hash of a file
* `calcFileSHA256(stream: NodeJS.ReadableStream): Promise<string>` - Calculate SHA256 hash of a stream
* `calcMD5(data: string): string` - Calculate MD5 hash of string data
* `calcPathSHA256Bytes(filePath: string): Promise<Buffer>` - Calculate SHA256 hash as Buffer
* `calcFileSHA256Bytes(stream: NodeJS.ReadableStream): Promise<Buffer>` - Calculate SHA256 hash of stream as Buffer

### File Functions

* `getFileSize(filePath: string): number` - Get the size of a file
* `readChunk(filePath: string, start: number, end: number): Promise<Buffer>` - Read a chunk of a file
* `ensureDir(dirPath: string): void` - Ensure directory exists

### Network Functions

* `checkConnectivity(host: string, port: number): Promise<boolean>` - Check network connectivity
* `pingHost(host: string): Promise<PingResponse>` - Ping a host

### String Functions

* `toBase64(data: string): string` - Convert string to base64
* `fromBase64(data: string): string` - Convert base64 to string
* `toHex(data: string): string` - Convert string to hex
* `fromHex(data: string): string` - Convert hex to string

### Time Functions

* `formatTimestamp(timestamp: number): string` - Format timestamp to readable string
* `getCurrentTimestamp(): number` - Get current timestamp

## Gateway Utilities

The utility functions play a critical role in gateway operations, particularly for authentication and communication with the CESS storage network.

### Gateway Authentication Functions

When interacting with CESS gateways, you need specific utilities to sign messages and authenticate:

```typescript
import { getWrappedMsg, safeSignUnixTime } from '@cessnetwork/util';

// Example: Gateway authentication preparation
// The signature and message are then used to obtain a token from the gateway
// as demonstrated in the @cessnetwork/api gateway operations
async function prepareGatewayAuthentication() {
  const mnemonic = process.env.CESS_PRIVATE_KEY || 'your twelve word mnemonic phrase or private key here';
  
  // Step 1: Create a timestamp message to sign
  const sign_message = Date.now().toString();
  
  // Step 2: Wrap the message with <Bytes> tags for proper signature format
  const wrappedMsg = getWrappedMsg(sign_message);
  
  // Step 3: Sign the timestamp with your mnemonic
  const signature = safeSignUnixTime(sign_message, mnemonic);
  
  console.log('Timestamp message:', sign_message);
  console.log('Wrapped message for signing:', wrappedMsg);
  console.log('Signature:', signature);
 
  // create cess client and verify it
  // const verifyRes = cess.keyring.verify(getWrappedMsg(sign_message), signature, cess.getPublicKey())
  // console.log('verify result:', verifyRes);
}

prepareGatewayAuthentication();
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.cess.network/developer/cess-sdk/sdk-js/util.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.