@katanga/sdk-core

Core types, ABIs, and utilities for the Katanga agent-to-agent marketplace protocol on Flare Network.

Install

npm install @katanga/sdk-core

What's included

| Module | Purpose | |--------|---------| | ABIs | KatangaMarket, KatangaEscrow (+ FDC methods), KatangaReputation, FDC system contracts | | Types | Solidity struct mirrors, Schema.org Product metadata, EscrowState, Supabase DB types | | Constants | Chain definitions (Coston2/Flare), contract addresses, CHAIN_REGISTRY, FDC constants | | Client | Viem client factory (createKatangaClient) for Coston2/Flare | | x402 | XRPL settlement types — SettlementRail (evm, xrpl-x402, xrpl-fdc) | | FDC | Flare Data Connector client — cross-chain XRP payment attestation and Merkle proof retrieval | | SyncEngine | Polling scheduler with circuit breaker, DeltaDetector, StockSnapshot, PriceSnapshot, FulfillmentSnapshot | | Credentials | CredentialStore interface, EnvCredentialStore (KATANGA_SOURCE_{ID}_{FIELD}), MemoryCredentialStore | | Telemetry | AgentTelemetry interface, ConsoleTelemetry, NoopTelemetry | | IPFS | KatangaIPFS — upload/fetch Schema.org listing metadata via Pinata |

Usage

import {
  katangaMarketAbi,
  katangaEscrowAbi,
  CONTRACTS,
  coston2,
  getChainConfig,
  CHAIN_REGISTRY,
  type ListingMetadata,
  EscrowState,
} from "@katanga/sdk-core";

// Get chain config for Coston2 testnet
const config = getChainConfig(114);
console.log(config.displayName);     // "Flare (Testnet)"
console.log(config.contracts.escrow); // "0x5a1BEB..."
console.log(config.settlement);       // ["evm", "xrpl-fdc"]

FDC Payment Attestation

Verify native XRP payments on XRPL via the Flare Data Connector:

import { verifyXrpPaymentViaFdc, hashXrplAddress } from "@katanga/sdk-core";

// 1. Hash XRPL addresses for on-chain comparison
const buyerHash = hashXrplAddress("rBuyerXRPAddress");

// 2. Full FDC verification flow (~3-5 min)
const proof = await verifyXrpPaymentViaFdc(
  publicClient, walletClient, "coston2", xrplTxHash,
  { onPoll: (ms) => console.log(`Waiting ${ms / 1000}s...`) }
);

// 3. Submit proof to escrow contract
await walletClient.writeContract({
  address: escrowAddress,
  abi: katangaEscrowAbi,
  functionName: "createEscrowWithXrpProof",
  args: [listingId, quantity, shippingHash, proof.roundId, proof.proof, proof.merkleProof],
});

SyncEngine

import { SyncEngine, DEFAULT_CIRCUIT_BREAKER, ConsoleTelemetry } from "@katanga/sdk-core";

const engine = new SyncEngine(DEFAULT_CIRCUIT_BREAKER, new ConsoleTelemetry("my-agent"));
engine.on("stock_changed", (event) => {
  console.log(`${event.sku}: ${event.current.quantityAvailable} units`);
});
engine.scheduleTask({ name: "stock", intervalMs: 120_000, execute: async () => [] });

Credential Store

import { EnvCredentialStore } from "@katanga/sdk-core";

// Reads: KATANGA_SOURCE_SHOPIFY_TYPE=api_key, KATANGA_SOURCE_SHOPIFY_API_KEY=shpat_...
const store = new EnvCredentialStore();
const creds = await store.get("shopify"); // { type: "api_key", apiKey: "shpat_..." }

License

MIT