SDK Overview

The EnergyAS JavaScript SDK is the recommended way to interact with EnergyAS from any Node.js or browser environment. It covers both reading data and submitting energy records on-chain.

The SDK exposes two independent classes:

Class	Purpose
`EnergyQuery`	Read data from the subgraph (no wallet required)
`EnergySDK`	Write to the contracts — register organizations, projects, attesters, and submit energy records

If you only need to display or analyze data, EnergyQuery is all you need. If you're building an automated reporting pipeline or a backend that submits readings, you'll use EnergySDK.

Installation

Terminal

npm install energy-attestation-sdk

The SDK requires Node.js 18+ and has ethers v6 as its only peer dependency for write operations. EnergyQuery uses the standard fetch API and has no additional dependencies.

Supported Networks

The SDK ships with built-in configuration for the following networks:

Network value	Chain	Status
`"amoy"`	Polygon Amoy (testnet)	Deployed
`"polygon"`	Polygon Mainnet	Deployed
`"celo"`	Celo Mainnet	Deployed
`"alfajores"`	Celo Alfajores (testnet)	EAS only

Pass the network name as a string when constructing either class.

Quick Example

JavaScript

import { EnergyQuery, EnergySDK } from 'energy-attestation-sdk';

// Read protocol stats — no wallet needed
const query = new EnergyQuery({
  network: 'polygon',
  apiKey: 'YOUR_THEGRAPH_API_KEY',
});

const protocol = await query.getProtocol();
console.log(`${protocol.totalProjects} projects, ${protocol.totalAttestations} records`);

// Submit a reading — requires a wallet
const sdk = await EnergySDK.fromPrivateKey({
  network: 'polygon',
  privateKey: process.env.PRIVATE_KEY,
});

const { uid } = await sdk.attestations.attest({
  projectId: 1,
  readings: [500_000n, 510_000n, 495_000n],  // Wh per interval
  readingIntervalMinutes: 60,
  fromTimestamp: Math.floor(Date.now() / 1000) - 3 * 3600,
  method: 'smart-meter-api',
});

console.log('Record submitted:', uid);

Error Handling

Both classes throw typed errors you can catch and inspect:

JavaScript

import { EnergySDKError, ConfigurationError, ContractRevertError } from 'energy-attestation-sdk';

try {
  await sdk.attestations.attest(params);
} catch (err) {
  if (err instanceof ContractRevertError) {
    console.error('Contract rejected the transaction:', err.code, err.message);
  } else if (err instanceof ConfigurationError) {
    console.error('Bad configuration:', err.message);
  } else {
    throw err;
  }
}

ConfigurationError — invalid arguments or missing configuration before any network call
ContractRevertError — the contract rejected the transaction, with a decoded error code from the contract's error catalog
TransactionError — the transaction was sent but failed during execution