@keldra/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Keldra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,93 @@
+# @keldra/sdk
+
+TypeScript SDK for the Keldra relay API.
+
+## Install
+
+```bash
+npm install @keldra/sdk
+```
+
+If you want encrypted payload transport:
+
+```bash
+npm install @keldra/sdk @stablelib/x25519 @stablelib/chacha20poly1305 @stablelib/blake2s
+```
+
+If you want framework adapters:
+
+```bash
+npm install @keldra/sdk ethers
+npm install @keldra/sdk viem
+```
+
+## Quick Start
+
+```ts
+import { KeldraClient } from "@keldra/sdk";
+
+const client = KeldraClient.create("kk_your_api_key");
+const result = await client.relay("ethereum", signedTxHex);
+const limits = await client.limits();
+const usage = await client.usage("2026-02-01", "2026-02-20");
+
+console.log(result.relayId, result.status, result.txHash);
+console.log(limits.tier, usage.totals.relays_submitted);
+```
+
+## Encrypted Transport
+
+```ts
+import { KeldraClient } from "@keldra/sdk";
+import { createEncryptFn } from "@keldra/sdk/crypto";
+
+const client = KeldraClient.builder()
+  .apiKey("kk_your_api_key")
+  .withEncryption(createEncryptFn())
+  .build();
+
+await client.fetchNoiseKey();
+const relay = await client.submit("ethereum", signedTxHex);
+```
+
+## Ethers Integration
+
+```ts
+import { KeldraClient } from "@keldra/sdk";
+import { wrapSigner } from "@keldra/sdk/ethers";
+
+const client = KeldraClient.create("kk_your_api_key");
+const signer = wrapSigner(originalSigner, { client, chain: "ethereum" });
+
+const tx = await signer.sendTransaction({ to, value });
+console.log(tx.hash);
+```
+
+## Viem Integration
+
+```ts
+import { KeldraClient } from "@keldra/sdk";
+import { wrapWalletClient } from "@keldra/sdk/viem";
+
+const client = KeldraClient.create("kk_your_api_key");
+const walletClient = wrapWalletClient(originalWalletClient, { client, chain: "ethereum" });
+
+const relayId = await walletClient.sendTransaction({ to, value });
+console.log(relayId);
+```
+
+## Exports
+
+- `@keldra/sdk` core client, types, errors
+- `@keldra/sdk/crypto` optional encryption helper
+- `@keldra/sdk/ethers` ethers wrapper
+- `@keldra/sdk/viem` viem wrapper
+
+## Requirements
+
+- Node.js 18+
+- API key from Keldra
+
+## License
+
+MIT

package/dist/client-03PUOnb6.d.ts

@@ -0,0 +1,38 @@
+import { K as KeldraClientConfig, D as DelayProfile, E as EncryptFn, C as Chain, h as RelayResult, g as RelayResponse, i as RelayStatusResponse, H as HealthResponse, b as ChainsResponse, M as MeLimitsResponse, d as MeUsageResponse } from './types-CL-VpP9K.js';
+
+declare class KeldraClient {
+    private readonly http;
+    private readonly gatewayUrl;
+    private readonly defaultDelayProfile;
+    private readonly confirmationTimeoutMs;
+    private readonly pollIntervalMs;
+    private noisePublicKey?;
+    private noiseKid?;
+    private readonly encryptFn?;
+    constructor(config: KeldraClientConfig);
+    static create(apiKey: string): KeldraClient;
+    static builder(): KeldraClientBuilder;
+    relay(chain: Chain, signedTx: string): Promise<RelayResult>;
+    submit(chain: Chain, signedTx: string): Promise<RelayResponse>;
+    status(relayId: string): Promise<RelayStatusResponse>;
+    waitForConfirmation(relayId: string): Promise<RelayStatusResponse>;
+    health(): Promise<HealthResponse>;
+    chains(): Promise<ChainsResponse>;
+    limits(): Promise<MeLimitsResponse>;
+    usage(from: string, to: string): Promise<MeUsageResponse>;
+    fetchNoiseKey(): Promise<void>;
+    get encrypted(): boolean;
+}
+declare class KeldraClientBuilder {
+    private config;
+    apiKey(key: string): this;
+    gatewayUrl(url: string): this;
+    delayProfile(profile: DelayProfile): this;
+    timeout(ms: number): this;
+    pollInterval(ms: number): this;
+    noisePublicKey(key: string, kid: string): this;
+    withEncryption(fn: EncryptFn): this;
+    build(): KeldraClient;
+}
+
+export { KeldraClient as K, KeldraClientBuilder as a };

package/dist/client-Bm1hg0EA.d.cts

@@ -0,0 +1,38 @@
+import { K as KeldraClientConfig, D as DelayProfile, E as EncryptFn, C as Chain, h as RelayResult, g as RelayResponse, i as RelayStatusResponse, H as HealthResponse, b as ChainsResponse, M as MeLimitsResponse, d as MeUsageResponse } from './types-CL-VpP9K.cjs';
+
+declare class KeldraClient {
+    private readonly http;
+    private readonly gatewayUrl;
+    private readonly defaultDelayProfile;
+    private readonly confirmationTimeoutMs;
+    private readonly pollIntervalMs;
+    private noisePublicKey?;
+    private noiseKid?;
+    private readonly encryptFn?;
+    constructor(config: KeldraClientConfig);
+    static create(apiKey: string): KeldraClient;
+    static builder(): KeldraClientBuilder;
+    relay(chain: Chain, signedTx: string): Promise<RelayResult>;
+    submit(chain: Chain, signedTx: string): Promise<RelayResponse>;
+    status(relayId: string): Promise<RelayStatusResponse>;
+    waitForConfirmation(relayId: string): Promise<RelayStatusResponse>;
+    health(): Promise<HealthResponse>;
+    chains(): Promise<ChainsResponse>;
+    limits(): Promise<MeLimitsResponse>;
+    usage(from: string, to: string): Promise<MeUsageResponse>;
+    fetchNoiseKey(): Promise<void>;
+    get encrypted(): boolean;
+}
+declare class KeldraClientBuilder {
+    private config;
+    apiKey(key: string): this;
+    gatewayUrl(url: string): this;
+    delayProfile(profile: DelayProfile): this;
+    timeout(ms: number): this;
+    pollInterval(ms: number): this;
+    noisePublicKey(key: string, kid: string): this;
+    withEncryption(fn: EncryptFn): this;
+    build(): KeldraClient;
+}
+
+export { KeldraClient as K, KeldraClientBuilder as a };

package/dist/crypto/index.cjs

@@ -0,0 +1,98 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});// src/crypto/noise.ts
+var _x25519 = require('@stablelib/x25519');
+var _chacha20poly1305 = require('@stablelib/chacha20poly1305');
+var _blake2s = require('@stablelib/blake2s');
+var PROTOCOL_NAME = "Noise_NK_25519_ChaChaPoly_BLAKE2s";
+var HASHLEN = 32;
+async function encryptForGateway(plaintext, gatewayPublicKeyHex) {
+  const rs = hexToBytes(gatewayPublicKeyHex);
+  if (rs.length !== 32) {
+    throw new Error(`Expected 32-byte public key, got ${rs.length} bytes`);
+  }
+  const protocolBytes = new TextEncoder().encode(PROTOCOL_NAME);
+  let h;
+  if (protocolBytes.length <= HASHLEN) {
+    h = new Uint8Array(HASHLEN);
+    h.set(protocolBytes);
+  } else {
+    h = _blake2s.hash.call(void 0, protocolBytes, HASHLEN);
+  }
+  let ck = new Uint8Array(h);
+  h = _blake2s.hash.call(void 0, concat(h, new Uint8Array(0)), HASHLEN);
+  h = _blake2s.hash.call(void 0, concat(h, rs), HASHLEN);
+  const ephemeral = _x25519.generateKeyPair.call(void 0, );
+  const ePub = ephemeral.publicKey;
+  h = _blake2s.hash.call(void 0, concat(h, ePub), HASHLEN);
+  const dhResult = _x25519.sharedKey.call(void 0, ephemeral.secretKey, rs);
+  const hkdfResult = hkdf(ck, dhResult, 2);
+  ck = new Uint8Array(hkdfResult[0]);
+  const k = new Uint8Array(hkdfResult[1]);
+  const nonce = nonceBytes(0n);
+  const aead = new (0, _chacha20poly1305.ChaCha20Poly1305)(k);
+  const ciphertext = aead.seal(nonce, plaintext, h);
+  return concat(ePub, ciphertext);
+}
+function hexToBytes(hex) {
+  const cleaned = hex.startsWith("0x") ? hex.slice(2) : hex;
+  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 concat(...arrays) {
+  const totalLen = arrays.reduce((sum, a) => sum + a.length, 0);
+  const result = new Uint8Array(totalLen);
+  let offset = 0;
+  for (const a of arrays) {
+    result.set(a, offset);
+    offset += a.length;
+  }
+  return result;
+}
+function hkdf(chainingKey, inputKeyMaterial, numOutputs) {
+  const tempKey = hmacBlake2s(chainingKey, inputKeyMaterial);
+  const outputs = [];
+  let prev = new Uint8Array(0);
+  for (let i = 1; i <= numOutputs; i++) {
+    const input = concat(prev, new Uint8Array([i]));
+    prev = new Uint8Array(hmacBlake2s(tempKey, input));
+    outputs.push(prev);
+  }
+  return outputs;
+}
+function hmacBlake2s(key, data) {
+  const blockSize = 64;
+  let paddedKey;
+  if (key.length > blockSize) {
+    paddedKey = new Uint8Array(blockSize);
+    paddedKey.set(_blake2s.hash.call(void 0, key, HASHLEN));
+  } else {
+    paddedKey = new Uint8Array(blockSize);
+    paddedKey.set(key);
+  }
+  const iPad = new Uint8Array(blockSize);
+  const oPad = new Uint8Array(blockSize);
+  for (let i = 0; i < blockSize; i++) {
+    iPad[i] = paddedKey[i] ^ 54;
+    oPad[i] = paddedKey[i] ^ 92;
+  }
+  const inner = _blake2s.hash.call(void 0, concat(iPad, data), HASHLEN);
+  return _blake2s.hash.call(void 0, concat(oPad, inner), HASHLEN);
+}
+function nonceBytes(n) {
+  const nonce = new Uint8Array(12);
+  const view = new DataView(nonce.buffer);
+  view.setUint32(4, Number(n & 0xffffffffn), true);
+  view.setUint32(8, Number(n >> 32n & 0xffffffffn), true);
+  return nonce;
+}
+
+// src/crypto/index.ts
+function createEncryptFn() {
+  return encryptForGateway;
+}
+
+
+
+exports.createEncryptFn = createEncryptFn; exports.encryptForGateway = encryptForGateway;

package/dist/crypto/index.d.cts

@@ -0,0 +1,7 @@
+export { E as EncryptFn } from '../types-CL-VpP9K.cjs';
+
+declare function encryptForGateway(plaintext: Uint8Array, gatewayPublicKeyHex: string): Promise<Uint8Array>;
+
+declare function createEncryptFn(): typeof encryptForGateway;
+
+export { createEncryptFn, encryptForGateway };

package/dist/crypto/index.d.ts

@@ -0,0 +1,7 @@
+export { E as EncryptFn } from '../types-CL-VpP9K.js';
+
+declare function encryptForGateway(plaintext: Uint8Array, gatewayPublicKeyHex: string): Promise<Uint8Array>;
+
+declare function createEncryptFn(): typeof encryptForGateway;
+
+export { createEncryptFn, encryptForGateway };

package/dist/crypto/index.js

@@ -0,0 +1,98 @@
+// src/crypto/noise.ts
+import { generateKeyPair, sharedKey } from "@stablelib/x25519";
+import { ChaCha20Poly1305 } from "@stablelib/chacha20poly1305";
+import { hash as blake2sHash } from "@stablelib/blake2s";
+var PROTOCOL_NAME = "Noise_NK_25519_ChaChaPoly_BLAKE2s";
+var HASHLEN = 32;
+async function encryptForGateway(plaintext, gatewayPublicKeyHex) {
+  const rs = hexToBytes(gatewayPublicKeyHex);
+  if (rs.length !== 32) {
+    throw new Error(`Expected 32-byte public key, got ${rs.length} bytes`);
+  }
+  const protocolBytes = new TextEncoder().encode(PROTOCOL_NAME);
+  let h;
+  if (protocolBytes.length <= HASHLEN) {
+    h = new Uint8Array(HASHLEN);
+    h.set(protocolBytes);
+  } else {
+    h = blake2sHash(protocolBytes, HASHLEN);
+  }
+  let ck = new Uint8Array(h);
+  h = blake2sHash(concat(h, new Uint8Array(0)), HASHLEN);
+  h = blake2sHash(concat(h, rs), HASHLEN);
+  const ephemeral = generateKeyPair();
+  const ePub = ephemeral.publicKey;
+  h = blake2sHash(concat(h, ePub), HASHLEN);
+  const dhResult = sharedKey(ephemeral.secretKey, rs);
+  const hkdfResult = hkdf(ck, dhResult, 2);
+  ck = new Uint8Array(hkdfResult[0]);
+  const k = new Uint8Array(hkdfResult[1]);
+  const nonce = nonceBytes(0n);
+  const aead = new ChaCha20Poly1305(k);
+  const ciphertext = aead.seal(nonce, plaintext, h);
+  return concat(ePub, ciphertext);
+}
+function hexToBytes(hex) {
+  const cleaned = hex.startsWith("0x") ? hex.slice(2) : hex;
+  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 concat(...arrays) {
+  const totalLen = arrays.reduce((sum, a) => sum + a.length, 0);
+  const result = new Uint8Array(totalLen);
+  let offset = 0;
+  for (const a of arrays) {
+    result.set(a, offset);
+    offset += a.length;
+  }
+  return result;
+}
+function hkdf(chainingKey, inputKeyMaterial, numOutputs) {
+  const tempKey = hmacBlake2s(chainingKey, inputKeyMaterial);
+  const outputs = [];
+  let prev = new Uint8Array(0);
+  for (let i = 1; i <= numOutputs; i++) {
+    const input = concat(prev, new Uint8Array([i]));
+    prev = new Uint8Array(hmacBlake2s(tempKey, input));
+    outputs.push(prev);
+  }
+  return outputs;
+}
+function hmacBlake2s(key, data) {
+  const blockSize = 64;
+  let paddedKey;
+  if (key.length > blockSize) {
+    paddedKey = new Uint8Array(blockSize);
+    paddedKey.set(blake2sHash(key, HASHLEN));
+  } else {
+    paddedKey = new Uint8Array(blockSize);
+    paddedKey.set(key);
+  }
+  const iPad = new Uint8Array(blockSize);
+  const oPad = new Uint8Array(blockSize);
+  for (let i = 0; i < blockSize; i++) {
+    iPad[i] = paddedKey[i] ^ 54;
+    oPad[i] = paddedKey[i] ^ 92;
+  }
+  const inner = blake2sHash(concat(iPad, data), HASHLEN);
+  return blake2sHash(concat(oPad, inner), HASHLEN);
+}
+function nonceBytes(n) {
+  const nonce = new Uint8Array(12);
+  const view = new DataView(nonce.buffer);
+  view.setUint32(4, Number(n & 0xffffffffn), true);
+  view.setUint32(8, Number(n >> 32n & 0xffffffffn), true);
+  return nonce;
+}
+
+// src/crypto/index.ts
+function createEncryptFn() {
+  return encryptForGateway;
+}
+export {
+  createEncryptFn,
+  encryptForGateway
+};

package/dist/ethers/index.cjs

@@ -0,0 +1,44 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } }// src/ethers/index.ts
+function wrapSigner(signer, options) {
+  return new Proxy(signer, {
+    get(target, prop, receiver) {
+      if (prop === "sendTransaction") {
+        return async (tx) => {
+          const populated = await target.populateTransaction(tx);
+          const signedTx = await target.signTransaction(populated);
+          const relayResponse = await options.client.submit(
+            options.chain,
+            signedTx
+          );
+          if (options.waitForConfirmation) {
+            const result = await options.client.waitForConfirmation(
+              relayResponse.relay_id
+            );
+            return {
+              ...relayResponse,
+              hash: _nullishCoalesce(result.tx_hash, () => ( relayResponse.relay_id))
+            };
+          }
+          return {
+            ...relayResponse,
+            hash: relayResponse.relay_id
+          };
+        };
+      }
+      return Reflect.get(target, prop, receiver);
+    }
+  });
+}
+var KeldraBroadcaster = class {
+  constructor(client, chain) {
+    this.client = client;
+    this.chain = chain;
+  }
+  async broadcastTransaction(signedTx) {
+    return this.client.submit(this.chain, signedTx);
+  }
+};
+
+
+
+exports.KeldraBroadcaster = KeldraBroadcaster; exports.wrapSigner = wrapSigner;

package/dist/ethers/index.d.cts

@@ -0,0 +1,18 @@
+import { Signer } from 'ethers';
+import { K as KeldraClient } from '../client-Bm1hg0EA.cjs';
+import { C as Chain, g as RelayResponse } from '../types-CL-VpP9K.cjs';
+
+interface KeldraBroadcasterOptions {
+    client: KeldraClient;
+    chain: Chain;
+    waitForConfirmation?: boolean;
+}
+declare function wrapSigner(signer: Signer, options: KeldraBroadcasterOptions): Signer;
+declare class KeldraBroadcaster {
+    private readonly client;
+    private readonly chain;
+    constructor(client: KeldraClient, chain: Chain);
+    broadcastTransaction(signedTx: string): Promise<RelayResponse>;
+}
+
+export { KeldraBroadcaster, type KeldraBroadcasterOptions, wrapSigner };

package/dist/ethers/index.d.ts

@@ -0,0 +1,18 @@
+import { Signer } from 'ethers';
+import { K as KeldraClient } from '../client-03PUOnb6.js';
+import { C as Chain, g as RelayResponse } from '../types-CL-VpP9K.js';
+
+interface KeldraBroadcasterOptions {
+    client: KeldraClient;
+    chain: Chain;
+    waitForConfirmation?: boolean;
+}
+declare function wrapSigner(signer: Signer, options: KeldraBroadcasterOptions): Signer;
+declare class KeldraBroadcaster {
+    private readonly client;
+    private readonly chain;
+    constructor(client: KeldraClient, chain: Chain);
+    broadcastTransaction(signedTx: string): Promise<RelayResponse>;
+}
+
+export { KeldraBroadcaster, type KeldraBroadcasterOptions, wrapSigner };

package/dist/ethers/index.js

@@ -0,0 +1,44 @@
+// src/ethers/index.ts
+function wrapSigner(signer, options) {
+  return new Proxy(signer, {
+    get(target, prop, receiver) {
+      if (prop === "sendTransaction") {
+        return async (tx) => {
+          const populated = await target.populateTransaction(tx);
+          const signedTx = await target.signTransaction(populated);
+          const relayResponse = await options.client.submit(
+            options.chain,
+            signedTx
+          );
+          if (options.waitForConfirmation) {
+            const result = await options.client.waitForConfirmation(
+              relayResponse.relay_id
+            );
+            return {
+              ...relayResponse,
+              hash: result.tx_hash ?? relayResponse.relay_id
+            };
+          }
+          return {
+            ...relayResponse,
+            hash: relayResponse.relay_id
+          };
+        };
+      }
+      return Reflect.get(target, prop, receiver);
+    }
+  });
+}
+var KeldraBroadcaster = class {
+  constructor(client, chain) {
+    this.client = client;
+    this.chain = chain;
+  }
+  async broadcastTransaction(signedTx) {
+    return this.client.submit(this.chain, signedTx);
+  }
+};
+export {
+  KeldraBroadcaster,
+  wrapSigner
+};