Symbioticfi Relay Stats Ts

https://github.com/symbioticfi/relay-stats-ts
Admin
TypeScript utilities for deriving Symbiotic validator-set data from on-chain contracts, mirroring...
Tokens:11,134
Snippets:59
Trust Score:7.1
License:MIT
Update:9 months ago
Show doc for...
Tokens:
Raw
### Build and Install Library Dependencies (Bash)

Source: https://github.com/symbioticfi/relay-stats-ts/blob/main/examples/README.md

Commands to install project dependencies, build the library, and then install example-specific dependencies. This ensures the example uses the latest built version of the relay-stats-ts library.

```bash
npm install
npm run build
cd examples
npm install
```

--------------------------------

### Run Relay Stats Example (Bash)

Source: https://github.com/symbioticfi/relay-stats-ts/blob/main/examples/README.md

Commands to execute the relay-stats-ts example script. Two methods are provided: direct TypeScript execution using `npm start` (recommended for Node 18/20) and execution via compiled JavaScript output (compatible with newer Node versions).

```bash
# Direct TypeScript execution (Node 18/20)
console.log('Running using ts-node...');
npm start

# Compiled output execution (any recent Node version)
console.log('Running compiled output...');
npm run build
node dist/example.js
```

--------------------------------

### Basic TypeScript Example Configuration (TypeScript)

Source: https://github.com/symbioticfi/relay-stats-ts/blob/main/examples/README.md

Illustrative TypeScript code snippet showing how to configure the `rpcUrls`, `driverAddress.chainId`, and `driverAddress.address` within the `example.ts` file. This configuration is essential for connecting to the Symbiotic driver contracts.

```typescript
const rpcUrls = [
  "http://localhost:8545",
  "http://localhost:8546"
];
const driverAddress = {
  chainId: 31337,
  address: "0xE1A1629C2a0447eA1e787527329805B234ac605C"
};
```

--------------------------------

### Install Relay Stats TS from npm or yarn

Source: https://github.com/symbioticfi/relay-stats-ts/blob/main/README.md

Installs the @symbioticfi/relay-stats-ts package using either npm or yarn. Requires Node.js version 18 or newer.

```bash
npm install @symbioticfi/relay-stats-ts
# or
yarn add @symbioticfi/relay-stats-ts
```

--------------------------------

### Install and Build Relay Stats TS Locally

Source: https://github.com/symbioticfi/relay-stats-ts/blob/main/README.md

Installs project dependencies, compiles TypeScript code to JavaScript, and allows local imports from the src or dist folders. Requires Git, Node.js, and npm.

```bash
git clone https://github.com/symbioticfi/relay-stats-ts.git
cd relay-stats-ts
npm install
npm run build
```

--------------------------------

### Configure Relay Stats Environment Variables (Bash)

Source: https://github.com/symbioticfi/relay-stats-ts/blob/main/examples/README.md

Export environment variables to configure the relay-stats-ts example without editing the `example.ts` file. These variables specify RPC URLs, the driver contract's chain ID, and its address.

```bash
export RELAY_STATS_RPC_URLS='["http://localhost:8545","http://localhost:8546"]'
export RELAY_STATS_DRIVER_CHAIN_ID=31337
export RELAY_STATS_DRIVER_ADDRESS=0xE1A1629C2a0447eA1e787527329805B234ac605C
```

--------------------------------

### Development Commands for relay-stats-ts

Source: https://github.com/symbioticfi/relay-stats-ts/blob/main/README.md

Standard npm commands for developing and maintaining the relay-stats-ts project. These include installing dependencies, linting code for style consistency, checking code formatting, and building the project.

```bash
npm install
npm run lint
npm run format:check
npm run build
```

--------------------------------

### Custom Caching Implementation with relay-stats-ts

Source: https://context7.com/symbioticfi/relay-stats-ts/llms.txt

Provides examples of implementing the CacheInterface for persisting validator sets, network configs, and aggregator data. Includes in-memory and Redis cache implementations to optimize repeated queries.

```typescript
import { ValidatorSetDeriver, CacheInterface } from '@symbioticfi/relay-stats-ts';

// In-memory cache implementation
class MemoryCache implements CacheInterface {
  private storage = new Map<string, Map<string, unknown>>();

  async get(epoch: number, key: string): Promise<unknown | null> {
    const epochBucket = this.storage.get(`epoch_${epoch}`);
    return epochBucket?.get(key) ?? null;
  }

  async set(epoch: number, key: string, value: unknown): Promise<void> {
    const bucketKey = `epoch_${epoch}`;
    let epochBucket = this.storage.get(bucketKey);
    if (!epochBucket) {
      epochBucket = new Map();
      this.storage.set(bucketKey, epochBucket);
    }
    epochBucket.set(key, value);
  }

  async delete(epoch: number, key: string): Promise<void> {
    const epochBucket = this.storage.get(`epoch_${epoch}`);
    epochBucket?.delete(key);
  }

  async clear(epoch: number): Promise<void> {
    this.storage.delete(`epoch_${epoch}`);
  }
}

// Redis cache implementation example
class RedisCache implements CacheInterface {
  constructor(private redis: any) {}

  async get(epoch: number, key: string): Promise<unknown | null> {
    const value = await this.redis.get(`epoch:${epoch}:${key}`);
    return value ? JSON.parse(value) : null;
  }

  async set(epoch: number, key: string, value: unknown): Promise<void> {
    await this.redis.set(
      `epoch:${epoch}:${key}`,
      JSON.stringify(value),
      'EX',
      86400 * 7 // 7 days TTL
    );
  }

  async delete(epoch: number, key: string): Promise<void> {
    await this.redis.del(`epoch:${epoch}:${key}`);
  }

  async clear(epoch: number): Promise<void> {
    const keys = await this.redis.keys(`epoch:${epoch}:*`);
    if (keys.length > 0) {
      await this.redis.del(...keys);
    }
  }
}

// Use cache with deriver
const cache = new MemoryCache();
const deriver = await ValidatorSetDeriver.create({
  rpcUrls: ['https://ethereum.publicnode.com'],
  driverAddress: { chainId: 1, address: '0xE1A1629C2a0447eA1e787527329805B234ac605C' },
  cache,
  maxSavedEpochs: 100
});

// First call hits RPC
const valset1 = await deriver.getValidatorSet(5, true);
console.log('First call: fetched from RPC and cached');

// Second call uses cache (much faster)
const valset2 = await deriver.getValidatorSet(5, true);
console.log('Second call: retrieved from cache');

```

--------------------------------

### Implement Cache Interface with MapCache in TypeScript

Source: https://github.com/symbioticfi/relay-stats-ts/blob/main/README.md

Demonstrates how to implement the CacheInterface for the ValidatorSetDeriver using a TypeScript Map. This allows for custom caching solutions like in-memory stores. The MapCache provides basic get, set, delete, and clear operations, namespaced by epoch and a string key.

```typescript
import type { CacheInterface } from '@symbioticfi/relay-stats-ts';

class MapCache implements CacheInterface {
  private buckets = new Map<number, Map<string, unknown>>();

  async get(epoch: number, key: string) {
    return this.buckets.get(epoch)?.get(key) ?? null;
  }

  async set(epoch: number, key: string, value: unknown) {
    let bucket = this.buckets.get(epoch);
    if (!bucket) {
      bucket = new Map();
      this.buckets.set(epoch, bucket);
    }
    bucket.set(key, value);
  }

  async delete(epoch: number, key: string) {
    const bucket = this.buckets.get(epoch);
    if (!bucket) return;
    bucket.delete(key);
    if (bucket.size === 0) {
      this.buckets.delete(epoch);
    }
  }

  async clear(epoch: number) {
    this.buckets.delete(epoch);
  }
}

const deriver = await ValidatorSetDeriver.create({
  rpcUrls: ["..."],
  driverAddress: {...},
  cache: new MapCache(),
});
```

--------------------------------

### Get Validator Set Settlement Statuses

Source: https://github.com/symbioticfi/relay-stats-ts/blob/main/README.md

Retrieves the commitment status for validator set settlements for a given epoch without fetching associated logs. This is useful when only the commitment status is needed.

```typescript
const settlements = await deriver.getValSetSettlementStatuses({ epoch });
settlements.forEach(({ settlement, committed }) => {
  console.log(`Settlement ${settlement.address} committed=${committed}`);
});
```

--------------------------------

### Get Aggregator Extra Data

Source: https://github.com/symbioticfi/relay-stats-ts/blob/main/README.md

Retrieves extra data for aggregators, supporting 'zk' mode or custom key tags for specific selection. This function is useful for advanced data retrieval beyond the default configuration.

```typescript
const extraData = await deriver.getAggregatorsExtraData('zk');
extraData.forEach(({ key, value }) => console.log(key, value));
```

--------------------------------

### ValidatorSetDeriver.create()

Source: https://context7.com/symbioticfi/relay-stats-ts/llms.txt

Initializes a ValidatorSetDeriver instance. This static factory method sets up the deriver by connecting to specified RPC endpoints and configuring the driver contract address. It performs initial connectivity checks before returning a ready-to-use deriver object.

```APIDOC
## ValidatorSetDeriver.create()

### Description
Initializes a validator set deriver with RPC endpoints and driver contract configuration. This static factory method validates chain connectivity and ensures all required chains are accessible before returning the deriver instance.

### Method
`static create(options: { rpcUrls: string[]; driverAddress: { chainId: number; address: string }; cache?: CacheInterface | null; maxSavedEpochs?: number })`

### Endpoint
N/A (Static factory method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
import { ValidatorSetDeriver } from '@symbioticfi/relay-stats-ts';

const deriver = await ValidatorSetDeriver.create({
  rpcUrls: [
    'https://ethereum.publicnode.com',
    'https://arbitrum.publicnode.com'
  ],
  driverAddress: {
    chainId: 1,
    address: '0xE1A1629C2a0447eA1e787527329805B234ac605C'
  },
  cache: null, // Optional: provide CacheInterface implementation
  maxSavedEpochs: 100 // Optional: cache retention limit
});

console.log('Deriver initialized successfully');
```

### Response
#### Success Response (200)
- **deriver** (ValidatorSetDeriver) - An initialized instance of ValidatorSetDeriver.

#### Response Example
```javascript
// On successful initialization, the deriver object is returned.
// The console log in the example indicates success.
console.log('Deriver initialized successfully');
```
```

--------------------------------

### Fetch Network Configuration with TypeScript

Source: https://context7.com/symbioticfi/relay-stats-ts/llms.txt

Retrieves the current network configuration for a given epoch, including voting power providers, key registries, settlements, and quorum thresholds. Requires the '@symbioticfi/relay-stats-ts' library.

```typescript
import { ValidatorSetDeriver } from '@symbioticfi/relay-stats-ts';

const deriver = await ValidatorSetDeriver.create({
  rpcUrls: ['https://ethereum.publicnode.com'],
  driverAddress: { chainId: 1, address: '0xE1A1629C2a0447eA1e787527329805B234ac605C' }
});

const config = await deriver.getCurrentNetworkConfig();

console.log('Voting Power Providers:');
config.votingPowerProviders.forEach(provider => {
  console.log(`  Chain ${provider.chainId}: ${provider.address}`);
});

console.log(`Keys Provider: Chain ${config.keysProvider.chainId}, ${config.keysProvider.address}`);

console.log('Settlements:');
config.settlements.forEach(settlement => {
  console.log(`  Chain ${settlement.chainId}: ${settlement.address}`);
});

console.log(`Verification Type: ${config.verificationType}`); // 0 = ZK, 1 = Simple
console.log(`Max Voting Power: ${config.maxVotingPower}`);
console.log(`Min Inclusion Voting Power: ${config.minInclusionVotingPower}`);
console.log(`Max Validators: ${config.maxValidatorsCount}`);
console.log(`Required Key Tags: ${config.requiredKeyTags.join(', ')}`);
console.log(`Required Header Key Tag: ${config.requiredHeaderKeyTag}`);

config.quorumThresholds.forEach(threshold => {
  console.log(`Quorum for key tag ${threshold.keyTag}: ${threshold.quorumThreshold}`);
});
```

--------------------------------

### SSZ Encoding and Merkle Proofs with relay-stats-ts

Source: https://context7.com/symbioticfi/relay-stats-ts/llms.txt

Converts validator sets to SSZ format, computes Merkle roots, and generates cryptographic proofs for on-chain verification using the @symbioticfi/relay-stats-ts library. It demonstrates serialization, root computation, and verification against headers.

```typescript
import {
  validatorSetToSszValidators,
  serializeValidatorSet,
  getValidatorSetRoot,
  sszTreeRoot,
  bytesToHex
} from '@symbioticfi/relay-stats-ts';
import { ValidatorSetDeriver } from '@symbioticfi/relay-stats-ts';

const deriver = await ValidatorSetDeriver.create({
  rpcUrls: ['https://ethereum.publicnode.com'],
  driverAddress: { chainId: 1, address: '0xE1A1629C2a0447eA1e787527329805B234ac605C' }
});

const validatorSet = await deriver.getCurrentValidatorSet();

// Convert to SSZ format
const sszValidators = validatorSetToSszValidators(validatorSet);
console.log(`SSZ Validators: ${sszValidators.Validators.length}`);

// Serialize to bytes
const serialized = serializeValidatorSet(sszValidators);
console.log(`Serialized Length: ${serialized.length} bytes`);
console.log(`Serialized Hex: ${bytesToHex(serialized)}`);

// Compute SSZ Merkle root
const sszRoot = getValidatorSetRoot(sszValidators);
console.log(`SSZ Merkle Root: ${bytesToHex(sszRoot)}`);

// Get SSZ tree root as hex string (convenience method)
const treeRootHex = sszTreeRoot(validatorSet);
console.log(`SSZ Tree Root (hex): ${treeRootHex}`);

// Verify root matches header
const header = deriver.getValidatorSetHeader(validatorSet);
if (treeRootHex === header.validatorsSszMRoot) {
  console.log('✅ SSZ root matches validator set header');
}
```

--------------------------------

### Validator Set Header Utilities - Generation and Hashing

Source: https://context7.com/symbioticfi/relay-stats-ts/llms.txt

Utilities for generating, encoding, and hashing validator set headers. This includes calculating active voting power, obtaining header details, ABI encoding for on-chain use, and verifying header hashes.

```typescript
import { ValidatorSetDeriver } from '@symbioticfi/relay-stats-ts';

const deriver = await ValidatorSetDeriver.create({
  rpcUrls: ['https://ethereum.publicnode.com'],
  driverAddress: { chainId: 1, address: '0xE1A1629C2a0447eA1e787527329805B234ac605C' }
});

const validatorSet = await deriver.getCurrentValidatorSet();

// Get total active voting power
const activeVotingPower = deriver.getTotalActiveVotingPower(validatorSet);
console.log(`Total Active Voting Power: ${activeVotingPower}`);

// Generate validator set header
const header = deriver.getValidatorSetHeader(validatorSet);
console.log('Validator Set Header:');
console.log(`  Version: ${header.version}`);
console.log(`  Required Key Tag: ${header.requiredKeyTag}`);
console.log(`  Epoch: ${header.epoch}`);
console.log(`  Capture Timestamp: ${header.captureTimestamp}`);
console.log(`  Quorum Threshold: ${header.quorumThreshold}`);
console.log(`  Total Voting Power: ${header.totalVotingPower}`);
console.log(`  Validators SSZ Merkle Root: ${header.validatorsSszMRoot}`);

// ABI encode the header for on-chain submission
const encodedHeader = deriver.abiEncodeValidatorSetHeader(header);
console.log(`ABI Encoded Header: ${encodedHeader}`);

// Hash the header (Keccak256)
const headerHash = deriver.hashValidatorSetHeader(header);
console.log(`Header Hash: ${headerHash}`);

// Compute header hash directly from validator set
const directHash = deriver.getValidatorSetHeaderHash(validatorSet);
console.log(`Direct Hash from ValidatorSet: ${directHash}`);

// Verify hashes match
if (headerHash === directHash) {
  console.log('✅ Header hash verification passed');
}

```

--------------------------------

### Epoch Timeline Queries - Boundaries and Conversions

Source: https://context7.com/symbioticfi/relay-stats-ts/llms.txt

Query epoch boundaries, durations, and convert timestamps to epoch indices. This is useful for historical analysis and synchronization, providing details about current, next, and specific epochs.

```typescript
import { ValidatorSetDeriver } from '@symbioticfi/relay-stats-ts';

const deriver = await ValidatorSetDeriver.create({
  rpcUrls: ['https://ethereum.publicnode.com'],
  driverAddress: { chainId: 1, address: '0xE1A1629C2a0447eA1e787527329805B234ac605C' }
});

// Get current epoch information
const currentEpoch = await deriver.getCurrentEpoch();
const currentEpochStart = await deriver.getCurrentEpochStart();
const currentEpochDuration = await deriver.getCurrentEpochDuration();

console.log(`Current Epoch: ${currentEpoch}`);
console.log(`Started at: ${currentEpochStart} (Unix timestamp)`);
console.log(`Duration: ${currentEpochDuration} seconds`);

// Get next epoch information
const nextEpoch = await deriver.getNextEpoch();
const nextEpochStart = await deriver.getNextEpochStart();
const nextEpochDuration = await deriver.getNextEpochDuration();

console.log(`Next Epoch: ${nextEpoch}`);
console.log(`Will start at: ${nextEpochStart}`);
console.log(`Duration: ${nextEpochDuration} seconds`);

// Query specific epoch
const epoch5Start = await deriver.getEpochStart(5);
const epoch5Duration = await deriver.getEpochDuration(5);
console.log(`Epoch 5: started at ${epoch5Start}, duration ${epoch5Duration}s`);

// Convert timestamp to epoch index
const timestamp = Math.floor(Date.now() / 1000);
const epochIndex = await deriver.getEpochIndex(timestamp);
console.log(`Timestamp ${timestamp} belongs to epoch ${epochIndex}`);

// Calculate epoch end time
const epoch5End = epoch5Start + epoch5Duration;
console.log(`Epoch 5 ended at: ${epoch5End}`);

```

--------------------------------

### Initialize ValidatorSetDeriver with TypeScript

Source: https://context7.com/symbioticfi/relay-stats-ts/llms.txt

Creates an instance of `ValidatorSetDeriver` by providing RPC endpoints and the driver contract address. This factory method ensures chain connectivity and returns a ready-to-use deriver. Optional parameters include a cache implementation and a limit for saved epochs.

```typescript
import { ValidatorSetDeriver } from '@symbioticfi/relay-stats-ts';

const deriver = await ValidatorSetDeriver.create({
  rpcUrls: [
    'https://ethereum.publicnode.com',
    'https://arbitrum.publicnode.com'
  ],
  driverAddress: {
    chainId: 1,
    address: '0xE1A1629C2a0447eA1e787527329805B234ac605C'
  },
  cache: null, // Optional: provide CacheInterface implementation
  maxSavedEpochs: 100 // Optional: cache retention limit
});

// Deriver is now ready to fetch validator sets
console.log('Deriver initialized successfully');
```

--------------------------------

### Fetch Epoch Data with Validator Set, Network, and Settlement Info (TypeScript)

Source: https://context7.com/symbioticfi/relay-stats-ts/llms.txt

Fetches a complete snapshot of an epoch, including validator set details, network configuration, aggregator data, settlement statuses, and optional validator set events. This function requires the 'ValidatorSetDeriver' from '@symbioticfi/relay-stats-ts' and takes an epoch number and optional flags for finalized status, network data, and event inclusion as input. It returns a detailed epoch snapshot object.

```typescript
import { ValidatorSetDeriver } from '@symbioticfi/relay-stats-ts';

const deriver = await ValidatorSetDeriver.create({
  rpcUrls: ['https://ethereum.publicnode.com'],
  driverAddress: { chainId: 1, address: '0xE1A1629C2a0447eA1e787527329805B234ac605C' }
});

const epochSnapshot = await deriver.getEpochData({
  epoch: 10,
  finalized: true,
  includeNetworkData: true,
  includeValSetEvent: true
});

console.log(`Epoch: ${epochSnapshot.epoch}`);
console.log(`Finalized: ${epochSnapshot.finalized}`);
console.log(`Epoch Start: ${epochSnapshot.epochStart}`);

console.log(`\nValidator Set:`);
console.log(`  Status: ${epochSnapshot.validatorSet.status}`);
console.log(`  Integrity: ${epochSnapshot.validatorSet.integrity}`);
console.log(`  Total Voting Power: ${epochSnapshot.validatorSet.totalVotingPower}`);
console.log(`  Active Validators: ${epochSnapshot.validatorSet.validators.filter(v => v.isActive).length}`);

if (epochSnapshot.networkData) {
  console.log(`\nNetwork Data:`);
  console.log(`  Address: ${epochSnapshot.networkData.address}`);
  console.log(`  Subnetwork: ${epochSnapshot.networkData.subnetwork}`);
}

if (epochSnapshot.aggregatorsExtraData) {
  console.log(`\nAggregator Extra Data: ${epochSnapshot.aggregatorsExtraData.length} entries`);
}

if (epochSnapshot.settlementStatuses) {
  console.log(`\nSettlement Statuses:`);
  epochSnapshot.settlementStatuses.forEach(status => {
    console.log(`  Chain ${status.settlement.chainId}: committed=${status.committed}`);
    if (status.headerHash) console.log(`    Header Hash: ${status.headerHash}`);
  });
}

if (epochSnapshot.valSetEvents) {
  console.log(`\nValidator Set Events:`);
  epochSnapshot.valSetEvents.forEach(eventLog => {
    if (eventLog.event) {
      console.log(`  Chain ${eventLog.settlement.chainId}:`);
      console.log(`    Kind: ${eventLog.event.kind}`);
      console.log(`    Block: ${eventLog.event.blockNumber}`);
      console.log(`    Tx: ${eventLog.event.transactionHash}`);
    }
  });
}

```

--------------------------------

### Fetch Current Validator Set with ValidatorSetDeriver

Source: https://github.com/symbioticfi/relay-stats-ts/blob/main/README.md

Creates a ValidatorSetDeriver instance to connect to the ValSet driver and retrieve the current validator set. It logs epoch, active validators, settlement status, and integrity.

```typescript
import { ValidatorSetDeriver } from '@symbioticfi/relay-stats-ts';

const deriver = await ValidatorSetDeriver.create({
  rpcUrls: ['https://ethereum.publicnode.com'],
  driverAddress: {
    chainId: 1,
    address: '0xDriverAddress',
  },
});

const validatorSet = await deriver.getCurrentValidatorSet();
console.log(`Epoch: ${validatorSet.epoch}`);
console.log(`Active validators: ${validatorSet.validators.filter(v => v.isActive).length}`);
console.log(`Settlement status: ${validatorSet.status}`);
console.log(`Integrity: ${validatorSet.integrity}`);
```

--------------------------------

### Fetch Single-Call Epoch Snapshot Data

Source: https://github.com/symbioticfi/relay-stats-ts/blob/main/README.md

Retrieves comprehensive epoch data in a single request, including validator set, network metadata, log events, and aggregator extras. It supports options for finalized status and inclusion of specific data types.

```typescript
const snapshot = await deriver.getEpochData({
  epoch,
  finalized: true,
  includeNetworkData: true,
  includeValSetEvent: true,
});

console.log(snapshot.validatorSet.status);
console.log(snapshot.networkData?.address);
console.log(snapshot.aggregatorsExtraData?.length ?? 0);
console.log(snapshot.settlementStatuses?.map((s) => ({
  chainId: s.settlement.chainId,
  committed: s.committed,
})));
console.log(snapshot.valSetEvents?.map((entry) => ({
  chainId: entry.settlement.chainId,
  hasEvent: Boolean(entry.event),
})));
```

--------------------------------

### getValidatorSet() and getCurrentValidatorSet()

Source: https://context7.com/symbioticfi/relay-stats-ts/llms.txt

Retrieves validator set information for a specified epoch or the current epoch. This includes details like total voting power, active validators, keys, vaults, and settlement commitment status.

```APIDOC
## getValidatorSet() and getCurrentValidatorSet()

### Description
Retrieve the complete validator set for a specific epoch or the current epoch, including all validators with their voting powers, keys, vaults, and settlement commitment status.

### Method
- `getValidatorSet(epoch: number, includeVaults: boolean): Promise<ValidatorSet>`
- `getCurrentValidatorSet(): Promise<ValidatorSet>`

### Endpoint
N/A (Instance methods)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
import { ValidatorSetDeriver } from '@symbioticfi/relay-stats-ts';

const deriver = await ValidatorSetDeriver.create({
  rpcUrls: ['https://ethereum.publicnode.com'],
  driverAddress: {
    chainId: 1,
    address: '0xE1A1629C2a0447eA1e787527329805B234ac605C'
  }
});

// Get current validator set
const currentValset = await deriver.getCurrentValidatorSet();
console.log(`Epoch: ${currentValset.epoch}`);
console.log(`Total validators: ${currentValset.validators.length}`);
console.log(`Active validators: ${currentValset.validators.filter(v => v.isActive).length}`);
console.log(`Total voting power: ${currentValset.totalVotingPower}`);
console.log(`Status: ${currentValset.status}`); // 'committed' | 'pending' | 'missing'
console.log(`Integrity: ${currentValset.integrity}`); // 'valid' | 'invalid'

// Get specific epoch
const epoch5Valset = await deriver.getValidatorSet(5, true);
epoch5Valset.validators.forEach(validator => {
  console.log(`Operator: ${validator.operator}`);
  console.log(`Voting power: ${validator.votingPower}`);
  console.log(`Active: ${validator.isActive}`);
  console.log(`Keys: ${validator.keys.length}`);
  console.log(`Vaults: ${validator.vaults.length}`);

  validator.vaults.forEach(vault => {
    console.log(`  Vault ${vault.vault} on chain ${vault.chainId}: ${vault.votingPower} VP`);
    if (vault.collateral) {
      console.log(`    Collateral: ${vault.collateral} (${vault.collateralSymbol})`);
    }
  });
});
```

### Response
#### Success Response (200)
- **ValidatorSet** (object)
  - **epoch** (number) - The epoch number.
  - **validators** (array) - An array of validator objects.
    - **operator** (string) - The operator address of the validator.
    - **votingPower** (string) - The voting power of the validator (as a string, e.g., '1000000000000000000').
    - **isActive** (boolean) - Indicates if the validator is currently active.
    - **keys** (array) - Array of cryptographic keys associated with the validator.
    - **vaults** (array) - Array of vault objects (if `includeVaults` is true or for current set).
      - **vault** (string) - Identifier for the vault.
      - **chainId** (number) - The chain ID where the vault is registered.
      - **votingPower** (string) - Voting power contributed by this vault.
      - **collateral** (string | null) - The amount of collateral, if any.
      - **collateralSymbol** (string | null) - The symbol of the collateral, if any.
  - **totalVotingPower** (string) - The total voting power of all validators in the set.
  - **status** (string) - The settlement status of the validator set ('committed', 'pending', 'missing').
  - **integrity** (string) - The integrity status of the validator set ('valid', 'invalid').

#### Response Example
```json
{
  "epoch": 10,
  "validators": [
    {
      "operator": "0xabc...",
      "votingPower": "1500000000000000000",
      "isActive": true,
      "keys": ["0xkey1...", "0xkey2..."],
      "vaults": [
        {
          "vault": "0xvault1...",
          "chainId": 1,
          "votingPower": "1000000000000000000",
          "collateral": "50000000000000000000",
          "collateralSymbol": "ETH"
        }
      ]
    }
    // ... other validators
  ],
  "totalVotingPower": "10000000000000000000",
  "status": "committed",
  "integrity": "valid"
}
```
```

--------------------------------

### Retrieve Validator Set Log Events

Source: https://github.com/symbioticfi/relay-stats-ts/blob/main/README.md

Fetches on-chain metadata for validator-set commitment events, including block number, timestamp, and transaction hash, along with parsed header data. It efficiently loads events only when the validator set status is 'committed'.

```typescript
const events = await deriver.getValSetLogEvents({ epoch, finalized: true });

events.forEach(({ settlement, committed, event }) => {
  console.log(`Settlement ${settlement.address} committed=${committed}`);
  if (event) {
    console.log('  kind:', event.kind);
    console.log('  blockTimestamp:', event.blockTimestamp);
    console.log('  txHash:', event.transactionHash);
  }
});
```

--------------------------------

### Retrieve Network Metadata with TypeScript

Source: https://context7.com/symbioticfi/relay-stats-ts/llms.txt

Fetches auxiliary network metadata, including network address, subnetwork ID, and EIP-712 domain information from a settlement contract. This function utilizes the '@symbioticfi/relay-stats-ts' library.

```typescript
import { ValidatorSetDeriver } from '@symbioticfi/relay-stats-ts';

const deriver = await ValidatorSetDeriver.create({
  rpcUrls: ['https://ethereum.publicnode.com'],
  driverAddress: { chainId: 1, address: '0xE1A1629C2a0447eA1e787527329805B234ac605C' }
});

const networkData = await deriver.getNetworkData();

console.log(`Network Address: ${networkData.address}`);
console.log(`Subnetwork ID: ${networkData.subnetwork}`);

console.log('EIP-712 Domain:');
console.log(`  Name: ${networkData.eip712Data.name}`);
console.log(`  Version: ${networkData.eip712Data.version}`);
console.log(`  Chain ID: ${networkData.eip712Data.chainId}`);
console.log(`  Verifying Contract: ${networkData.eip712Data.verifyingContract}`);
console.log(`  Salt: ${networkData.eip712Data.salt}`);
console.log(`  Extensions: ${networkData.eip712Data.extensions.length}`);

// Optionally specify a specific settlement
const config = await deriver.getCurrentNetworkConfig();
if (config.settlements.length > 0) {
  const settlement = config.settlements[0];
  const specificNetworkData = await deriver.getNetworkData(settlement, true);
  console.log(`Network data from settlement on chain ${settlement.chainId}`);
}
```

--------------------------------

### Query Validator Set Settlement Statuses

Source: https://context7.com/symbioticfi/relay-stats-ts/llms.txt

Retrieve commitment status and header hashes for validator sets across settlements without fetching full event logs. This function supports filtering by epoch and specific settlements, and can check for finalized statuses.

```typescript
import { ValidatorSetDeriver } from '@symbioticfi/relay-stats-ts';

const deriver = await ValidatorSetDeriver.create({
  rpcUrls: ['https://ethereum.publicnode.com'],
  driverAddress: { chainId: 1, address: '0xE1A1629C2a0447eA1e787527329805B234ac605C' }
});

// Get settlement statuses for current epoch
const statuses = await deriver.getValSetSettlementStatuses({ finalized: true });

statuses.forEach(status => {
  console.log(`Settlement: Chain ${status.settlement.chainId}, ${status.settlement.address}`);
  console.log(`  Committed: ${status.committed}`);
  console.log(`  Header Hash: ${status.headerHash || 'null'}`);
  console.log(`  Last Committed Epoch: ${status.lastCommittedEpoch}`);
});

// Check specific epoch
const epoch5Statuses = await deriver.getValSetSettlementStatuses({
  epoch: 5,
  finalized: true
});

const allCommitted = epoch5Statuses.every(s => s.committed);
console.log(`All settlements committed for epoch 5: ${allCommitted}`);

// Check specific settlements
const customSettlements = [
  { chainId: 1, address: '0xSettlement1' },
  { chainId: 42161, address: '0xSettlement2' }
];
const customStatuses = await deriver.getValSetSettlementStatuses({
  epoch: 10,
  settlements: customSettlements,
  finalized: true
});

```

--------------------------------

### Retrieve Current and Specific Epoch Validator Sets with TypeScript

Source: https://context7.com/symbioticfi/relay-stats-ts/llms.txt

Fetches the current validator set or a validator set for a specific epoch. The retrieved data includes epoch number, validator details (operator, voting power, active status, keys, vaults), total voting power, and settlement status and integrity.

```typescript
import { ValidatorSetDeriver } from '@symbioticfi/relay-stats-ts';

const deriver = await ValidatorSetDeriver.create({
  rpcUrls: ['https://ethereum.publicnode.com'],
  driverAddress: {
    chainId: 1,
    address: '0xE1A1629C2a0447eA1e787527329805B234ac605C'
  }
});

// Get current validator set
const currentValset = await deriver.getCurrentValidatorSet();
console.log(`Epoch: ${currentValset.epoch}`);
console.log(`Total validators: ${currentValset.validators.length}`);
console.log(`Active validators: ${currentValset.validators.filter(v => v.isActive).length}`);
console.log(`Total voting power: ${currentValset.totalVotingPower}`);
console.log(`Status: ${currentValset.status}`); // 'committed' | 'pending' | 'missing'
console.log(`Integrity: ${currentValset.integrity}`); // 'valid' | 'invalid'

// Get specific epoch
const epoch5Valset = await deriver.getValidatorSet(5, true);
epoch5Valset.validators.forEach(validator => {
  console.log(`Operator: ${validator.operator}`);
  console.log(`Voting power: ${validator.votingPower}`);
  console.log(`Active: ${validator.isActive}`);
  console.log(`Keys: ${validator.keys.length}`);
  console.log(`Vaults: ${validator.vaults.length}`);

  validator.vaults.forEach(vault => {
    console.log(`  Vault ${vault.vault} on chain ${vault.chainId}: ${vault.votingPower} VP`);
    if (vault.collateral) {
      console.log(`    Collateral: ${vault.collateral} (${vault.collateralSymbol})`);
    }
  });
});
```

--------------------------------

### Retrieve Validator Set Commitment Log Events (TypeScript)

Source: https://context7.com/symbioticfi/relay-stats-ts/llms.txt

Retrieves log events related to validator set commitments from settlement contracts. This function can fetch events for the current epoch or a specific epoch, with options to filter by settlement contracts and specify finalized status. It returns an array of event logs, each containing settlement information and parsed event data, including optional quorum proofs.

```typescript
import { ValidatorSetDeriver } from '@symbioticfi/relay-stats-ts';

const deriver = await ValidatorSetDeriver.create({
  rpcUrls: ['https://ethereum.publicnode.com'],
  driverAddress: { chainId: 1, address: '0xE1A1629C2a0447eA1e787527329805B234ac605C' }
});

// Get events for current epoch from all settlements
const events = await deriver.getValSetLogEvents({ finalized: true });

events.forEach(eventLog => {
  console.log(`Settlement: Chain ${eventLog.settlement.chainId}, ${eventLog.settlement.address}`);
  console.log(`Committed: ${eventLog.committed}`);

  if (eventLog.event) {
    console.log(`  Event Kind: ${eventLog.event.kind}`); // 'genesis' | 'commit' 
    console.log(`  Epoch: ${eventLog.event.header.epoch}`);
    console.log(`  Capture Timestamp: ${eventLog.event.header.captureTimestamp}`);
    console.log(`  Total Voting Power: ${eventLog.event.header.totalVotingPower}`);
    console.log(`  Validators SSZ Root: ${eventLog.event.header.validatorsSszMRoot}`);
    console.log(`  Block Number: ${eventLog.event.blockNumber}`);
    console.log(`  Block Timestamp: ${eventLog.event.blockTimestamp}`);
    console.log(`  Transaction Hash: ${eventLog.event.transactionHash}`);

    if (eventLog.event.quorumProof) {
      console.log(`  Quorum Proof Mode: ${eventLog.event.quorumProof.mode}`);
      if (eventLog.event.quorumProof.mode === 'simple') {
        console.log(`    Signers: ${eventLog.event.quorumProof.signers.length}`);
        console.log(`    Non-Signer Indices: ${eventLog.event.quorumProof.nonSignerIndices.length}`);
      } else {
        console.log(`    Signers Voting Power: ${eventLog.event.quorumProof.signersVotingPower}`);
      }
    }
  } else {
    console.log(`  Event: Not yet committed or unavailable`);
  }
});

// Get events for specific epoch and settlements
const specificEvents = await deriver.getValSetLogEvents({
  epoch: 5,
  settlements: [{ chainId: 1, address: '0xSettlement1' }],
  finalized: true
});

```

--------------------------------

### Generate Aggregator Extra Data with TypeScript

Source: https://context7.com/symbioticfi/relay-stats-ts/llms.txt

Creates aggregator extra data for simple or zero-knowledge verification modes, including cryptographic commitments and validator metadata. This function depends on the '@symbioticfi/relay-stats-ts' library and requires specifying the aggregator mode.

```typescript
import { ValidatorSetDeriver, AGGREGATOR_MODE } from '@symbioticfi/relay-stats-ts';

const deriver = await ValidatorSetDeriver.create({
  rpcUrls: ['https://ethereum.publicnode.com'],
  driverAddress: { chainId: 1, address: '0xE1A1629C2a0447eA1e787527329805B234ac605C' }
});

// Simple mode: generates validators keccak hash and aggregated G1 key
const simpleExtraData = await deriver.getAggregatorsExtraData(
  AGGREGATOR_MODE.SIMPLE,
  undefined, // Uses requiredKeyTags from config if not specified
  true, // finalized
  undefined // current epoch if not specified
);

console.log('Simple Mode Extra Data:');
simpleExtraData.forEach(entry => {
  console.log(`Key: ${entry.key}`);
  console.log(`Value: ${entry.value}`);
});

// ZK mode: generates total active validators count and MiMC-based hash
const zkExtraData = await deriver.getAggregatorsExtraData(
  AGGREGATOR_MODE.ZK,
  [0, 1], // Specific key tags
  true,
  5 // epoch 5
);

console.log('ZK Mode Extra Data:');
zkExtraData.forEach(entry => {
  console.log(`Key: ${entry.key}`);
  console.log(`Value: ${entry.value}`);
});
```
Tokens:
Raw