Vela Common TypeScript Library

TypeScript library for interacting with Vela. Provides P-521 ECDH encryption and a blockchain client optimized for browser applications.

Installation

npm install vela-common-ts ethers

Note: ethers v6 is a peer dependency and must be installed separately.

npm run build

This will build a browser-friendly version of the lib in the path: dist/index.js

Quick Start

import {
  VelaClient,
  RequestType,
  ethersSignerFromBrowser,
  stringToBytes
} from 'vela-common-ts';

// Connect to user's wallet (MetaMask, etc.)
const signer = await ethersSignerFromBrowser();

// Initialize the client
const client = new VelaClient(
  signer,
  false, // useAlternativeSign
  '0x...', // TEE Authenticator contract address
  '0x...'  // Processor Endpoint contract address
);

// Encrypt payload data for the TEE
const payload = stringToBytes(....);
const encryptedPayload = await client.encryptForTee(payload);

// Submit a request
const receipt = await client.submitRequestAndWaitForRequestId(
  1,                    // protocolVersion
  1,                    // applicationId
  RequestType.PROCESS,  // requestType
  encryptedPayload,     // payload
  0n,                   // depositAmount
  1000000000000000n     // maxFeeValue (wei)
);

console.log('Request ID:', receipt.requestId);

API Reference

Blockchain Client

VelaClient

Main client for interacting with Vela smart contracts.

const client = new VelaClient(
  signer: Signer,              // ethers.js Signer instance
  useAlternativeSign: boolean, // Use alternative signing method
  teeAuthenticatorAddress: string,
  processorEndpointAddress: string
);

Methods:

Method	Description
submitRequest(...)	Submit a request to the CCE
submitRequestAndWaitForRequestId(...)	Submit and wait for request ID
encryptForTee(data)	Encrypt data for the TEE
getTeePublicKey()	Get the TEE's public key
getSignerKeyPair()	Get the P-521 key pair derived from the signer
getRequestCompletedEvent(requestId, fromBlock, toBlock)	Query for request completion
getCurrentUserEvents(fromBlock, toBlock, applicationId, eventSubType, filter, stopAtFirst)	Get encrypted events for current user
decryptAndFilterEvents(events, filter, stopAtFirst)	Decrypt and filter events
getPendingPayments(address)	Get pending payments for an address
withdrawPayments(payee)	Withdraw payments for a payee

RequestType

enum RequestType {
  DEPLOYAPP = 0,
  PROCESS = 1,
  DEANONYMIZATION = 2,
  ASSOCIATEKEY = 3
}

Crypto Functions

Key Derivation

import {
  deriveP521PrivateKeyFromSigner,
  ethersSignerFromBrowser
} from 'vela-common-ts';

// Get signer from browser wallet
const signer = await ethersSignerFromBrowser();

// Derive P-521 key pair from signer
const keyPair = await deriveP521PrivateKeyFromSigner(signer, false);

Encryption/Decryption

import {
  encrypt,
  decrypt,
  encryptWithAES,
  decryptWithAES,
  importPublicKeyFromHex,
  importPrivateKeyFromHex,
  exportPublicKeyToHex,
  generateKeyPair,
  P521KeyPair
} from 'vela-common-ts';

// Encrypt message (ECDH + AES-GCM)
const ciphertext = await encrypt(
  senderKeyPair.privateKey,
  receiverPublicKey,
  messageBytes
);

// Decrypt message
const plaintext = await decrypt(
  receiverKeyPair.privateKey,
  senderPublicKey,
  ciphertext
);

// AES-only encryption/decryption
const aesCiphertext = await encryptWithAES(sharedKey, plaintext);
const aesPlaintext = await decryptWithAES(sharedKey, aesCiphertext);

// Generate a new P-521 key pair
const keyPair = await generateKeyPair();

// Import/export keys
const pubKey = await importPublicKeyFromHex(hexString);
const privKey = await importPrivateKeyFromHex(hexString);
const hexPubKey = await exportPublicKeyToHex(keyPair.publicKey);

Subgraph Client

The library provides a subgraph client for querying Vela indexed data (as an alternative to direct on-chain event queries).

import {
  createSubgraphClient,
  fetchAndDecryptUserEvents,
  userEventSortKey
} from 'vela-common-ts';

// Create a subgraph client
const subgraphClient = createSubgraphClient(subgraphUrl);

// Health check
await subgraphClient.healthCheck();

// Query completed requests
const result = await subgraphClient.getRequestCompletedByID(requestId);

// Query user events
const events = await subgraphClient.getUserEvents(applicationId, eventSubType, limit);

// Fetch and decrypt user events
const decryptedEvents = await fetchAndDecryptUserEvents(
  subgraphClient,
  keyPair,
  teePublicKey,
  applicationId,
  eventSubType,
  limit
);

Types:

Type	Description
SubgraphClient	Interface for subgraph operations
SubgraphClientImpl	Default implementation of SubgraphClient
MockSubgraphClient	Mock implementation for testing
RequestCompleted	Completed request projection from subgraph
UserEvent	User event projection from subgraph

Constants

import { CHALLENGE, HKDF_SALT, HKDF_INFO } from 'vela-common-ts';

Constant	Description
CHALLENGE	Challenge message used for key derivation signing
HKDF_SALT	Salt used in HKDF key derivation
HKDF_INFO	Info parameter used in HKDF key derivation

Browser Compatibility

This library is designed for modern browsers with Web Crypto API support:

• Chrome 60+
• Firefox 57+
• Safari 11+
• Edge 79+

The library uses:

• Web Crypto API for cryptographic operations
• ES Modules (ESM) format
• ES2020 target

Development

Build

npm install
npm run build

Run Tests

npm test

Type Check

npm run check

Update Contract Types

If vela contracts are updated, clone the Vela repository, then run:

cd contracts
npm install
npx hardhat compile

Copy the generated contracts/typechain-types folder to replace src/typechain-types in this repository.