@keldra/sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,331 @@
+// src/errors.ts
+var KeldraError = class _KeldraError extends Error {
+  code;
+  cause;
+  constructor(code, message, cause) {
+    super(message);
+    this.name = "KeldraError";
+    this.code = code;
+    this.cause = cause;
+  }
+  static http(message, cause) {
+    return new _KeldraError("HTTP", `HTTP request failed: ${message}`, cause);
+  }
+  static api(status, message) {
+    return new KeldraApiError(status, message);
+  }
+  static timeout(relayId, lastStatus) {
+    return new KeldraTimeoutError(relayId, lastStatus);
+  }
+  static invalidTransaction(message) {
+    return new _KeldraError(
+      "INVALID_TRANSACTION",
+      `Invalid transaction: ${message}`
+    );
+  }
+  static config(message) {
+    return new _KeldraError("CONFIG", `SDK configuration error: ${message}`);
+  }
+};
+var KeldraApiError = class extends KeldraError {
+  status;
+  constructor(status, message) {
+    super("API", `API error (HTTP ${status}): ${message}`);
+    this.name = "KeldraApiError";
+    this.status = status;
+  }
+};
+var KeldraTimeoutError = class extends KeldraError {
+  relayId;
+  lastStatus;
+  constructor(relayId, lastStatus) {
+    super(
+      "TIMEOUT",
+      `Relay ${relayId} timed out (last status: ${lastStatus})`
+    );
+    this.name = "KeldraTimeoutError";
+    this.relayId = relayId;
+    this.lastStatus = lastStatus;
+  }
+};
+
+// src/utils.ts
+function parseHex(hexStr) {
+  const cleaned = hexStr.startsWith("0x") ? hexStr.slice(2) : hexStr;
+  if (cleaned.length === 0) {
+    throw KeldraError.invalidTransaction("empty transaction");
+  }
+  if (cleaned.length % 2 !== 0 || !/^[0-9a-fA-F]+$/.test(cleaned)) {
+    throw KeldraError.invalidTransaction(`invalid hex: ${hexStr}`);
+  }
+  const bytes = new Uint8Array(cleaned.length / 2);
+  for (let i = 0; i < cleaned.length; i += 2) {
+    bytes[i / 2] = parseInt(cleaned.substring(i, i + 2), 16);
+  }
+  return bytes;
+}
+function toHex(bytes) {
+  return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function toBase64(bytes) {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(bytes).toString("base64");
+  }
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+function extractErrorMessage(body) {
+  try {
+    const parsed = JSON.parse(body);
+    if (typeof parsed?.error === "string") return parsed.error;
+  } catch {
+  }
+  return body;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/http.ts
+var HttpClient = class {
+  baseHeaders;
+  constructor(bearerToken) {
+    this.baseHeaders = { "Content-Type": "application/json" };
+    if (bearerToken) {
+      this.baseHeaders["Authorization"] = `Bearer ${bearerToken}`;
+    }
+  }
+  async get(url) {
+    return this.request("GET", url);
+  }
+  async post(url, body) {
+    return this.request("POST", url, body);
+  }
+  async request(method, url, body) {
+    let response;
+    try {
+      response = await fetch(url, {
+        method,
+        headers: this.baseHeaders,
+        body: body ? JSON.stringify(body) : void 0
+      });
+    } catch (err) {
+      throw KeldraError.http(String(err), err);
+    }
+    if (!response.ok) {
+      const text = await response.text().catch(() => "");
+      throw KeldraError.api(response.status, extractErrorMessage(text));
+    }
+    return response.json();
+  }
+};
+
+// src/padding.ts
+var BUCKETS = [512, 1024, 2048, 4096];
+function padTransaction(rawTx) {
+  const originalLen = rawTx.length;
+  const totalNeeded = originalLen + 4;
+  const bucket = BUCKETS.find((b) => b >= totalNeeded);
+  if (!bucket) {
+    throw new Error(
+      `Transaction too large: ${originalLen} bytes (max ${BUCKETS[BUCKETS.length - 1] - 4} bytes)`
+    );
+  }
+  const padded = new Uint8Array(bucket);
+  padded.set(rawTx, 0);
+  const paddingLen = bucket - totalNeeded;
+  if (paddingLen > 0) {
+    const randomBytes = crypto.getRandomValues(new Uint8Array(paddingLen));
+    padded.set(randomBytes, originalLen);
+  }
+  const view = new DataView(padded.buffer, padded.byteOffset);
+  view.setUint32(bucket - 4, originalLen, false);
+  return padded;
+}
+function unpadTransaction(padded) {
+  if (padded.length < 4) return null;
+  const view = new DataView(padded.buffer, padded.byteOffset);
+  const originalLen = view.getUint32(padded.length - 4, false);
+  if (originalLen > padded.length - 4) return null;
+  return padded.slice(0, originalLen);
+}
+
+// src/types.ts
+var TERMINAL_STATUSES = /* @__PURE__ */ new Set([
+  "confirmed",
+  "failed"
+]);
+
+// src/client.ts
+var DEFAULT_GATEWAY_URL = "http://localhost:3400";
+var DEFAULT_TIMEOUT_MS = 3e5;
+var DEFAULT_POLL_INTERVAL_MS = 2e3;
+var MAX_POLL_INTERVAL_MS = 15e3;
+var KeldraClient = class _KeldraClient {
+  http;
+  gatewayUrl;
+  defaultDelayProfile;
+  confirmationTimeoutMs;
+  pollIntervalMs;
+  noisePublicKey;
+  noiseKid;
+  encryptFn;
+  constructor(config) {
+    if (!config.apiKey) {
+      throw KeldraError.config("apiKey is required");
+    }
+    this.http = new HttpClient(config.apiKey);
+    this.gatewayUrl = (config.gatewayUrl ?? DEFAULT_GATEWAY_URL).replace(
+      /\/$/,
+      ""
+    );
+    this.defaultDelayProfile = config.delayProfile ?? "balanced";
+    this.confirmationTimeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.pollIntervalMs = config.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    this.noisePublicKey = config.noisePublicKey;
+    this.noiseKid = config.noiseKid;
+    this.encryptFn = config.encryptFn;
+  }
+  static create(apiKey) {
+    return new _KeldraClient({ apiKey });
+  }
+  static builder() {
+    return new KeldraClientBuilder();
+  }
+  async relay(chain, signedTx) {
+    const start = Date.now();
+    const response = await this.submit(chain, signedTx);
+    const result = await this.waitForConfirmation(response.relay_id);
+    return {
+      relayId: response.relay_id,
+      status: result.status,
+      txHash: result.tx_hash,
+      durationMs: Date.now() - start,
+      error: result.error
+    };
+  }
+  async submit(chain, signedTx) {
+    const rawBytes = parseHex(signedTx);
+    const padded = padTransaction(rawBytes);
+    let request;
+    if (this.noisePublicKey && this.noiseKid && this.encryptFn) {
+      const encrypted = await this.encryptFn(padded, this.noisePublicKey);
+      const b64 = toBase64(encrypted);
+      request = {
+        chain,
+        signed_tx: "",
+        options: { delay_profile: this.defaultDelayProfile },
+        encrypted_payload: b64,
+        noise_kid: this.noiseKid
+      };
+    } else {
+      request = {
+        chain,
+        signed_tx: `0x${toHex(padded)}`,
+        options: { delay_profile: this.defaultDelayProfile }
+      };
+    }
+    return this.http.post(
+      `${this.gatewayUrl}/v1/relay`,
+      request
+    );
+  }
+  async status(relayId) {
+    return this.http.get(
+      `${this.gatewayUrl}/v1/relay/${relayId}/status`
+    );
+  }
+  async waitForConfirmation(relayId) {
+    const deadline = Date.now() + this.confirmationTimeoutMs;
+    let interval = this.pollIntervalMs;
+    let lastStatus;
+    while (Date.now() < deadline) {
+      await sleep(interval);
+      try {
+        lastStatus = await this.status(relayId);
+        if (TERMINAL_STATUSES.has(lastStatus.status)) {
+          return lastStatus;
+        }
+      } catch {
+      }
+      interval = Math.min(interval * 2, MAX_POLL_INTERVAL_MS);
+    }
+    throw KeldraError.timeout(relayId, lastStatus?.status ?? "queued");
+  }
+  async health() {
+    return this.http.get(`${this.gatewayUrl}/v1/health`);
+  }
+  async chains() {
+    return this.http.get(`${this.gatewayUrl}/v1/chains`);
+  }
+  async limits() {
+    return this.http.get(`${this.gatewayUrl}/v1/me/limits`);
+  }
+  async usage(from, to) {
+    const params = new URLSearchParams({ from, to });
+    return this.http.get(
+      `${this.gatewayUrl}/v1/me/usage?${params.toString()}`
+    );
+  }
+  async fetchNoiseKey() {
+    const resp = await this.http.get(
+      `${this.gatewayUrl}/v1/noise-key`
+    );
+    this.noisePublicKey = resp.public_key;
+    this.noiseKid = resp.kid;
+  }
+  get encrypted() {
+    return !!(this.noisePublicKey && this.noiseKid && this.encryptFn);
+  }
+};
+var KeldraClientBuilder = class {
+  config = {};
+  apiKey(key) {
+    this.config.apiKey = key;
+    return this;
+  }
+  gatewayUrl(url) {
+    this.config.gatewayUrl = url;
+    return this;
+  }
+  delayProfile(profile) {
+    this.config.delayProfile = profile;
+    return this;
+  }
+  timeout(ms) {
+    this.config.timeoutMs = ms;
+    return this;
+  }
+  pollInterval(ms) {
+    this.config.pollIntervalMs = ms;
+    return this;
+  }
+  noisePublicKey(key, kid) {
+    this.config.noisePublicKey = key;
+    this.config.noiseKid = kid;
+    return this;
+  }
+  withEncryption(fn) {
+    this.config.encryptFn = fn;
+    return this;
+  }
+  build() {
+    if (!this.config.apiKey) {
+      throw KeldraError.config("apiKey is required");
+    }
+    return new KeldraClient(this.config);
+  }
+};
+export {
+  KeldraApiError,
+  KeldraClient,
+  KeldraClientBuilder,
+  KeldraError,
+  KeldraTimeoutError,
+  TERMINAL_STATUSES,
+  padTransaction,
+  unpadTransaction
+};

package/dist/types-CL-VpP9K.d.cts

@@ -0,0 +1,121 @@
+type Chain = 'ethereum' | 'arbitrum' | 'optimism' | 'base' | 'polygon';
+type DelayProfile = 'fast' | 'balanced' | 'maximum_privacy';
+type RelayStatus = 'queued' | 'batched' | 'injected' | 'confirmed' | 'failed';
+declare const TERMINAL_STATUSES: ReadonlySet<RelayStatus>;
+interface RelayRequest {
+    chain: Chain;
+    signed_tx: string;
+    options: RelayOptions;
+    encrypted_payload?: string;
+    noise_kid?: string;
+}
+interface RelayOptions {
+    delay_profile: DelayProfile;
+}
+interface RelayResponse {
+    relay_id: string;
+    estimated_broadcast_min_secs: number;
+    estimated_broadcast_max_secs: number;
+}
+interface RelayStatusResponse {
+    relay_id: string;
+    status: RelayStatus;
+    queued_at: string;
+    batched_at?: string;
+    injected_at?: string;
+    confirmed_at?: string;
+    tx_hash?: string;
+    error?: string;
+}
+interface RelayResult {
+    relayId: string;
+    status: RelayStatus;
+    txHash?: string;
+    durationMs: number;
+    error?: string;
+}
+interface HealthResponse {
+    status: string;
+    gateway_regions: string[];
+    injection_regions: string[];
+    supported_chains: string[];
+    stats: HealthStats;
+}
+interface HealthStats {
+    active_relays: number;
+    total_relays: number;
+    queued: number;
+    batched: number;
+    injected: number;
+    confirmed: number;
+    failed: number;
+}
+interface ChainsResponse {
+    chains: ChainConfig[];
+}
+interface ChainConfig {
+    chain: Chain;
+    name: string;
+    min_batch_size: number;
+    epoch_duration_secs: number;
+    injection_node_count: number;
+    confirmation_timeout_secs: number;
+    enabled: boolean;
+}
+interface NoiseKeyResponse {
+    kid: string;
+    public_key: string;
+    protocol: string;
+}
+interface MeLimitsResponse {
+    api_key: string;
+    key_id: string;
+    tier: string;
+    limits: EffectiveLimits;
+    usage: CurrentUsage;
+}
+interface EffectiveLimits {
+    requests_per_minute: number;
+    max_inflight: number;
+    monthly_quota_relays: number;
+    min_poll_interval_ms: number;
+    max_body_bytes: number;
+}
+interface CurrentUsage {
+    month: string;
+    monthly_relays_submitted: number;
+    monthly_remaining_relays: number;
+    inflight_relays: number;
+}
+interface MeUsageResponse {
+    daily: UsageDailyRow[];
+    totals: UsageTotals;
+}
+interface UsageDailyRow {
+    day: string;
+    api_key: string;
+    tier: string;
+    relays_submitted: number;
+    relays_confirmed: number;
+    relays_failed: number;
+    bytes_ingested: number;
+}
+interface UsageTotals {
+    relays_submitted: number;
+    relays_confirmed: number;
+    relays_failed: number;
+    bytes_ingested: number;
+}
+type EncryptFn = (plaintext: Uint8Array, gatewayPublicKeyHex: string) => Promise<Uint8Array>;
+interface KeldraClientConfig {
+    apiKey: string;
+    gatewayUrl?: string;
+    delayProfile?: DelayProfile;
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+    noisePublicKey?: string;
+    noiseKid?: string;
+    encryptFn?: EncryptFn;
+}
+
+export { type Chain as C, type DelayProfile as D, type EncryptFn as E, type HealthResponse as H, type KeldraClientConfig as K, type MeLimitsResponse as M, type NoiseKeyResponse as N, type RelayStatus as R, TERMINAL_STATUSES as T, type UsageDailyRow as U, type ChainConfig as a, type ChainsResponse as b, type HealthStats as c, type MeUsageResponse as d, type RelayOptions as e, type RelayRequest as f, type RelayResponse as g, type RelayResult as h, type RelayStatusResponse as i, type UsageTotals as j };

package/dist/types-CL-VpP9K.d.ts

@@ -0,0 +1,121 @@
+type Chain = 'ethereum' | 'arbitrum' | 'optimism' | 'base' | 'polygon';
+type DelayProfile = 'fast' | 'balanced' | 'maximum_privacy';
+type RelayStatus = 'queued' | 'batched' | 'injected' | 'confirmed' | 'failed';
+declare const TERMINAL_STATUSES: ReadonlySet<RelayStatus>;
+interface RelayRequest {
+    chain: Chain;
+    signed_tx: string;
+    options: RelayOptions;
+    encrypted_payload?: string;
+    noise_kid?: string;
+}
+interface RelayOptions {
+    delay_profile: DelayProfile;
+}
+interface RelayResponse {
+    relay_id: string;
+    estimated_broadcast_min_secs: number;
+    estimated_broadcast_max_secs: number;
+}
+interface RelayStatusResponse {
+    relay_id: string;
+    status: RelayStatus;
+    queued_at: string;
+    batched_at?: string;
+    injected_at?: string;
+    confirmed_at?: string;
+    tx_hash?: string;
+    error?: string;
+}
+interface RelayResult {
+    relayId: string;
+    status: RelayStatus;
+    txHash?: string;
+    durationMs: number;
+    error?: string;
+}
+interface HealthResponse {
+    status: string;
+    gateway_regions: string[];
+    injection_regions: string[];
+    supported_chains: string[];
+    stats: HealthStats;
+}
+interface HealthStats {
+    active_relays: number;
+    total_relays: number;
+    queued: number;
+    batched: number;
+    injected: number;
+    confirmed: number;
+    failed: number;
+}
+interface ChainsResponse {
+    chains: ChainConfig[];
+}
+interface ChainConfig {
+    chain: Chain;
+    name: string;
+    min_batch_size: number;
+    epoch_duration_secs: number;
+    injection_node_count: number;
+    confirmation_timeout_secs: number;
+    enabled: boolean;
+}
+interface NoiseKeyResponse {
+    kid: string;
+    public_key: string;
+    protocol: string;
+}
+interface MeLimitsResponse {
+    api_key: string;
+    key_id: string;
+    tier: string;
+    limits: EffectiveLimits;
+    usage: CurrentUsage;
+}
+interface EffectiveLimits {
+    requests_per_minute: number;
+    max_inflight: number;
+    monthly_quota_relays: number;
+    min_poll_interval_ms: number;
+    max_body_bytes: number;
+}
+interface CurrentUsage {
+    month: string;
+    monthly_relays_submitted: number;
+    monthly_remaining_relays: number;
+    inflight_relays: number;
+}
+interface MeUsageResponse {
+    daily: UsageDailyRow[];
+    totals: UsageTotals;
+}
+interface UsageDailyRow {
+    day: string;
+    api_key: string;
+    tier: string;
+    relays_submitted: number;
+    relays_confirmed: number;
+    relays_failed: number;
+    bytes_ingested: number;
+}
+interface UsageTotals {
+    relays_submitted: number;
+    relays_confirmed: number;
+    relays_failed: number;
+    bytes_ingested: number;
+}
+type EncryptFn = (plaintext: Uint8Array, gatewayPublicKeyHex: string) => Promise<Uint8Array>;
+interface KeldraClientConfig {
+    apiKey: string;
+    gatewayUrl?: string;
+    delayProfile?: DelayProfile;
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+    noisePublicKey?: string;
+    noiseKid?: string;
+    encryptFn?: EncryptFn;
+}
+
+export { type Chain as C, type DelayProfile as D, type EncryptFn as E, type HealthResponse as H, type KeldraClientConfig as K, type MeLimitsResponse as M, type NoiseKeyResponse as N, type RelayStatus as R, TERMINAL_STATUSES as T, type UsageDailyRow as U, type ChainConfig as a, type ChainsResponse as b, type HealthStats as c, type MeUsageResponse as d, type RelayOptions as e, type RelayRequest as f, type RelayResponse as g, type RelayResult as h, type RelayStatusResponse as i, type UsageTotals as j };

package/dist/viem/index.cjs

@@ -0,0 +1,34 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});// src/viem/index.ts
+function wrapWalletClient(walletClient, options) {
+  return {
+    ...walletClient,
+    sendTransaction: (async (args) => {
+      const request = await walletClient.prepareTransactionRequest(
+        args
+      );
+      const signedTx = await walletClient.signTransaction(request);
+      const response = await options.client.submit(
+        options.chain,
+        signedTx
+      );
+      return response.relay_id;
+    })
+  };
+}
+function keldraTransportAction(options) {
+  return {
+    async sendRawTransaction({
+      serializedTransaction
+    }) {
+      const response = await options.client.submit(
+        options.chain,
+        serializedTransaction
+      );
+      return response.relay_id;
+    }
+  };
+}
+
+
+
+exports.keldraTransportAction = keldraTransportAction; exports.wrapWalletClient = wrapWalletClient;

package/dist/viem/index.d.cts

@@ -0,0 +1,16 @@
+import { Transport, Chain as Chain$1, Account, WalletClient } from 'viem';
+import { K as KeldraClient } from '../client-Bm1hg0EA.cjs';
+import { C as Chain } from '../types-CL-VpP9K.cjs';
+
+interface KeldraViemOptions {
+    client: KeldraClient;
+    chain: Chain;
+}
+declare function wrapWalletClient<TTransport extends Transport = Transport, TChain extends Chain$1 | undefined = Chain$1 | undefined, TAccount extends Account | undefined = Account | undefined>(walletClient: WalletClient<TTransport, TChain, TAccount>, options: KeldraViemOptions): WalletClient<TTransport, TChain, TAccount>;
+declare function keldraTransportAction(options: KeldraViemOptions): {
+    sendRawTransaction({ serializedTransaction, }: {
+        serializedTransaction: string;
+    }): Promise<string>;
+};
+
+export { type KeldraViemOptions, keldraTransportAction, wrapWalletClient };

package/dist/viem/index.d.ts

@@ -0,0 +1,16 @@
+import { Transport, Chain as Chain$1, Account, WalletClient } from 'viem';
+import { K as KeldraClient } from '../client-03PUOnb6.js';
+import { C as Chain } from '../types-CL-VpP9K.js';
+
+interface KeldraViemOptions {
+    client: KeldraClient;
+    chain: Chain;
+}
+declare function wrapWalletClient<TTransport extends Transport = Transport, TChain extends Chain$1 | undefined = Chain$1 | undefined, TAccount extends Account | undefined = Account | undefined>(walletClient: WalletClient<TTransport, TChain, TAccount>, options: KeldraViemOptions): WalletClient<TTransport, TChain, TAccount>;
+declare function keldraTransportAction(options: KeldraViemOptions): {
+    sendRawTransaction({ serializedTransaction, }: {
+        serializedTransaction: string;
+    }): Promise<string>;
+};
+
+export { type KeldraViemOptions, keldraTransportAction, wrapWalletClient };

package/dist/viem/index.js

@@ -0,0 +1,34 @@
+// src/viem/index.ts
+function wrapWalletClient(walletClient, options) {
+  return {
+    ...walletClient,
+    sendTransaction: (async (args) => {
+      const request = await walletClient.prepareTransactionRequest(
+        args
+      );
+      const signedTx = await walletClient.signTransaction(request);
+      const response = await options.client.submit(
+        options.chain,
+        signedTx
+      );
+      return response.relay_id;
+    })
+  };
+}
+function keldraTransportAction(options) {
+  return {
+    async sendRawTransaction({
+      serializedTransaction
+    }) {
+      const response = await options.client.submit(
+        options.chain,
+        serializedTransaction
+      );
+      return response.relay_id;
+    }
+  };
+}
+export {
+  keldraTransportAction,
+  wrapWalletClient
+};