EQTY Core

EQTY Core Events Library - Base-compatible event chain and messaging for EQTY

Overview

This library provides a clean, Base-compatible implementation of event chains and messaging for the EQTY platform. It replaces the LTO Network private layer components with Ethereum wallet-native signing and Base blockchain anchoring.

Features

• Event Chains: Cryptographically linked events with Ethereum wallet signing
• Messaging: Encrypted messaging with wallet-based authentication
• Base Anchoring: Stateless smart contract anchoring on Base
• Wallet Integration: Native support for MetaMask, WalletConnect, and other Ethereum wallets
• TypeScript: Full TypeScript support with comprehensive type definitions

Installation

npm install eqty-core

Quick Start with Ethers

Basic Event Chain Usage

import { Event, EventChain, AnchorClient } from "eqty-core";
import { BrowserProvider, verifyTypedData, Contract } from "ethers";

// Connect to wallet
const provider = new BrowserProvider(window.ethereum);
const signer = await provider.getSigner();

const address = await signer.getAddress();
const { chainId: networkId } = await provider.getNetwork();

// Create an event chain
const chain = EventChain.create(address, networkId);

// Create event and add to chain
const event = new Event({ message: "Hello EQTY!" }, "application/json").addTo(chain);

// Sign event
await event.signWith(signer);

// Create anchor client using the network-specific contract address
const contract = new Contract(
  AnchorClient.contractAddress(Number(networkId)),
  AnchorClient.ABI,
  signer,
);
const anchorClient = new AnchorClient(contract as any);

// Anchor chain map
await anchorClient.anchor(chain.anchorMap());

// Validate a received event chain
chain.validate((address, domain, types, value, signature) =>
  verifyTypedData(domain, types, value, signature).toLowerCase() === address.toLowerCase()
);

Messaging

import { Message, AnchorClient } from "eqty-core";
import { BrowserProvider, Contract } from "ethers";

// Connect to wallet
const provider = new BrowserProvider(window.ethereum);
const signer = await provider.getSigner();
const { chainId: networkId } = await provider.getNetwork();

// Create a message
const message = new Message("Hello from EQTY!", "text/plain", {
  type: "greeting",
  title: "Welcome Message",
});

// Set the recipient and sign the message
await message
  .to("0x8dB7BC85A8ec23B2190D6dA004DE58FeFB2FBbAD")
  .signWith(signer);

// Create anchor client
const contract = new Contract(
  AnchorClient.contractAddress(Number(networkId)),
  AnchorClient.ABI,
  signer,
);
const anchorClient = new AnchorClient(contract as any);

// Anchor message hash to blockchain
await anchorClient.anchor(message.hash);

// Validate a received message
chain.validate((address, domain, types, value, signature) =>
  verifyTypedData(domain, types, value, signature).toLowerCase() === address.toLowerCase()
);

Quick Start with Viem

Basic Event Chain Usage

import { Event, EventChain, AnchorClient, ViemSigner, ViemContract } from "eqty-core";
import { createWalletClient, createPublicClient, custom, recoverTypedDataAddress } from "viem";
import { baseSepolia } from "viem/chains";

// Request accounts and set up viem wallet client with an account
const [address] = (await window.ethereum.request({ method: "eth_requestAccounts" })) as string[];

const walletClient = createWalletClient({
  account: address as `0x${string}`,
  chain: baseSepolia, // or base
  transport: custom(window.ethereum),
});

const publicClient = createPublicClient({
  chain: baseSepolia,
  transport: custom(window.ethereum),
});

// Create an EQTY signer for viem
const signer = new ViemSigner(walletClient);

// Create an event chain
const networkId = baseSepolia.id;
const chain = EventChain.create(address, networkId);

// Create event and add to chain
const event = new Event({ message: "Hello EQTY!" }, "application/json").addTo(chain);

// Sign event with viem signer
await event.signWith(signer);

// Set up ViemContract and AnchorClient
const contract = new ViemContract(
  publicClient,
  walletClient,
  AnchorClient.contractAddress(networkId),
);
const anchorClient = new AnchorClient(contract as any);

// Anchor chain map
await anchorClient.anchor(chain.anchorMap());

// Validate a received event chain
chain.validate(
  async (address, domain, types, value, signature) => {
    return await viemVerifyTypedData({
      address: address as `0x${string}`,
      domain: domain,
      types: types,
      primaryType: "Event",
      message: value,
      signature: signature as `0x${string}`,
    });
  }
);

Messaging

import { Message, AnchorClient, ViemSigner, ViemContract } from "eqty-core";
import { createWalletClient, createPublicClient, custom } from "viem";
import { baseSepolia } from "viem/chains";

// Set up viem wallet/public clients
const [address] = (await window.ethereum.request({ method: "eth_requestAccounts" })) as string[];

const walletClient = createWalletClient({
  account: address as `0x${string}`,
  chain: baseSepolia,
  transport: custom(window.ethereum),
});
const publicClient = createPublicClient({
  chain: baseSepolia,
  transport: custom(window.ethereum),
});

const signer = new ViemSigner(walletClient);
const networkId = baseSepolia.id;

// Create a message
const message = new Message("Hello from EQTY!", "text/plain", {
  type: "greeting",
  title: "Welcome Message",
});


// Set the recipient and sign the message
await message
  .to("0x8dB7BC85A8ec23B2190D6dA004DE58FeFB2FBbAD")
  .signWith(signer);

// Set up ViemContract and AnchorClient
const contract = new ViemContract(
  publicClient,
  walletClient,
  AnchorClient.contractAddress(networkId)
);
const anchorClient = new AnchorClient(contract as any);

// Anchor message hash to blockchain
await anchorClient.anchor(message.hash);

// Validate a received message
message.validate(
  async (address, domain, types, value, signature) => {
    return await viemVerifyTypedData({
      address: address as `0x${string}`,
      domain: domain,
      types: types,
      primaryType: "Event",
      message: value,
      signature: signature as `0x${string}`,
    });
  }
);

API Reference

Core Classes

Event

Represents a single event in an event chain.

class Event {
  constructor(data: any, mediaType?: string, previous?: string | Uint8Array);

  // Build and read
  addAttachment(name: string, data: Uint8Array, mediaType: string): this;
  addTo(chain: EventChain): this;
  get parsedData(): any;
  toJSON(): IEventJSON;

  // Signing & verification
  async signWith(signer: ISigner): Promise<this>;
  async verifySignature(verify: VerifyFn): Promise<boolean>;
  verifyHash(): boolean;

  // Static helpers
  static from(json: IEventJSON, defaultVersion?: number): Event;
}

EventChain

Manages a chain of cryptographically linked events.

class EventChain {
  // Factory
  static create(address: string, networkId: number, nonce?: Uint8Array): EventChain;
  withVerification(verify: VerifyFn): this;

  // Compose
  add(eventOrChain: Event | EventChain): this;
  addEvent(event: Event): this;
  addChain(chain: EventChain): this;
  has(event: Event): boolean;

  // State
  latestHash(): Uint8Array | undefined;
  initialHash(): Uint8Array | undefined;
  latestEvent(): Event | undefined;
  state(): Uint8Array;
  initialState(): Uint8Array;
  stateAt(length: number): Uint8Array;
  isSigned(): boolean;

  // Validation and metadata
  validate(verify: VerifyFn): Promise<void>;
  isCreatedBy(address: string, networkId: number): boolean;

  // Anchoring
  anchorMap: Array<{ key: Uint8Array; value: Uint8Array }>;

  // Serialization
  toJSON(): IEventChainJSON;
  static from(json: IEventChainJSON): EventChain;
}

Message

Represents a message with optional metadata that can be signed and anchored.

class Message {
  constructor(data: any, mediaType?: string, meta?: IMessageMeta);

  hash(): Uint8Array;
  to(recipient: string): Message;

  // Signing & verification
  async signWith(sender: ISigner): Promise<this>;
  isSigned(): boolean;
  async verifySignature(verify: VerifyFn): Promise<boolean>;
  verifyHash(): boolean;

  // Binary/JSON
  toJSON(): IMessageJSON;
  static fromJSON(json: IMessageJSON): Message;
  static fromBinary(data: Uint8Array): Message;
}

AnchorClient

Interfaces with the Base Anchor smart contract. You pass in a contract adapter that implements anchor() and maxAnchors().

class AnchorClient<T> {
  static readonly ABI: any;
  static contractAddress(networkId: number): `0x${string}`;

  constructor(contract: AnchorContract<T>);

  // Anchor 1 or many entries (Uint8Array inputs)
  anchor(input: Array<{ key: Uint8Array; value: Uint8Array }>): Promise<T>;
  anchor(key: Uint8Array, value: Uint8Array): Promise<T>;
  anchor(value: Array<Uint8Array>): Promise<T>;
  anchor(value: Uint8Array): Promise<T>;

  // Limits
  getMaxAnchors(): Promise<number>;
}

Binary Utilities

Binary

Extended Uint8Array with blockchain-specific functionality.

class Binary extends Uint8Array {
  // Encodings
  get base58(): string;
  get base64(): string;
  get hex(): string; // 0x-prefixed
  get hexRaw(): string; // without 0x

  // Hashing
  hash(): Binary;

  // Construction
  static from(value: string | ArrayLike<number> | Iterable<any>): Binary;
  static fromBase58(value: string): Binary;
  static fromBase64(value: string): Binary;
  static fromHex(value: string): Binary;
  static fromMultibase(value: string): Binary;

  // Numbers (big-endian)
  static fromInt16(value: number): Binary;
  static fromInt32(value: number): Binary;

  // Utilities
  static concat(...items: Array<ArrayLike<number>>): Binary;
}

Viem helpers

class ViemSigner<T extends IViemAccount> implements ISigner {
  constructor(client: IViemWalletClient<T>);
  getAddress(): Promise<string>;
  signTypedData(domain, types, value): Promise<string>;
}

class ViemContract<T extends IViemAccount> {
  constructor(publicClient: IViemPublicClient, walletClient: IViemWalletClient<T>, address: `0x${string}`);
  anchor(anchors: Array<{ key: `0x${string}`; value: `0x${string}` }>): Promise<void>;
  maxAnchors(): Promise<number>;
}

Migration from LTO

This library replaces the following LTO components:

LTO Component	EQTY Replacement	Notes
events/Event	Event	Uses Ethereum signing instead of LTO keypairs
events/EventChain	EventChain	Anchors to Base instead of LTO blockchain
messages/Message	Message	Wallet-native authentication
messages/Relay	Relay	Simplified for Base compatibility
Binary	Binary	Ported with minimal changes
LTO.anchor()	AnchorClient	Replaced with helper class to anchor using an smart contract

Development

Building

npm run build

Testing

npm test

Linting

npm run lint
npm run lint-fix

License

MIT