@aboutcircles/sdk-rpc 0.1.0

package/dist/rpc.js

@@ -0,0 +1,76 @@
+import { RpcClient } from './client';
+import { PathfinderMethods, QueryMethods, TrustMethods, BalanceMethods, AvatarMethods, ProfileMethods, TokenMethods, InvitationMethods, TransactionMethods, GroupMethods, } from './methods';
+/**
+ * Main RPC class for Circles protocol RPC interactions
+ *
+ * @example
+ * ```typescript
+ * // Use default RPC endpoint
+ * const rpc = new CirclesRpc();
+ *
+ * // Use custom RPC endpoint
+ * const rpc = new CirclesRpc('https://rpc.circlesubi.network/');
+ *
+ * // Find a path
+ * const path = await rpc.pathfinder.findPath({
+ *   Source: '0x749c930256b47049cb65adcd7c25e72d5de44b3b',
+ *   Sink: '0xde374ece6fa50e781e81aac78e811b33d16912c7',
+ *   TargetFlow: '99999999999999999999999999999999999'
+ * });
+ *
+ * // Query trust relations
+ * const trustRelations = await rpc.query.query({
+ *   Namespace: 'V_CrcV2',
+ *   Table: 'TrustRelations',
+ *   Columns: [],
+ *   Filter: [],
+ *   Order: []
+ * });
+ *
+ * // Get profile
+ * const profile = await rpc.profile.getProfileByAddress('0xc3a1428c04c426cdf513c6fc8e09f55ddaf50cd7');
+ * ```
+ */
+export class CirclesRpc {
+    client;
+    pathfinder;
+    query;
+    trust;
+    balance;
+    avatar;
+    profile;
+    token;
+    invitation;
+    transaction;
+    group;
+    /**
+     * Create a new CirclesRpc instance
+     *
+     * @param rpcUrl RPC URL to use (defaults to https://rpc.circlesubi.network/)
+     */
+    constructor(rpcUrl = 'https://rpc.circlesubi.network/') {
+        this.client = new RpcClient(rpcUrl);
+        this.pathfinder = new PathfinderMethods(this.client);
+        this.query = new QueryMethods(this.client);
+        this.trust = new TrustMethods(this.client);
+        this.balance = new BalanceMethods(this.client);
+        this.avatar = new AvatarMethods(this.client);
+        this.profile = new ProfileMethods(this.client);
+        this.token = new TokenMethods(this.client);
+        this.invitation = new InvitationMethods(this.client);
+        this.transaction = new TransactionMethods(this.client);
+        this.group = new GroupMethods(this.client);
+    }
+    /**
+     * Update the RPC URL
+     */
+    setRpcUrl(rpcUrl) {
+        this.client.setRpcUrl(rpcUrl);
+    }
+    /**
+     * Get the current RPC URL
+     */
+    getRpcUrl() {
+        return this.client.getRpcUrl();
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,82 @@
+import type { Address } from '@aboutcircles/sdk-types';
+/**
+ * RPC-specific types
+ * These types are specific to the RPC package and not shared across multiple packages
+ */
+/**
+ * Transaction history row (base data from RPC)
+ * Might include conversions between different circle representations
+ */
+export interface TransactionHistoryRow {
+    blockNumber: number;
+    timestamp: number;
+    transactionIndex: number;
+    logIndex: number;
+    transactionHash: string;
+    version: number;
+    from: Address;
+    to: Address;
+    id: string;
+    tokenAddress: Address;
+    value: string;
+    /** Human-readable circle amount (demurraged) */
+    circles?: number;
+    /** Atto-circles (demurraged, 18 decimals) */
+    attoCircles?: bigint;
+    /** Static circles (inflationary, human-readable) */
+    staticCircles?: number;
+    /** Atto-static circles (inflationary, 18 decimals) */
+    staticAttoCircles?: bigint;
+    /** Time Circles (CRC) human-readable */
+    crc?: number;
+    /** Atto-CRC (18 decimals) */
+    attoCrc?: bigint;
+}
+/**
+ * Search result profile with additional metadata
+ */
+export interface SearchResultProfile {
+    address: Address;
+    name: string;
+    description?: string;
+    previewImageUrl?: string;
+    imageUrl?: string;
+    location?: string;
+    geoLocation?: [number, number];
+    extensions?: Record<string, any>;
+    avatarType?: string;
+    CID?: string;
+    lastUpdatedAt?: number;
+    registeredName?: string | null;
+}
+/**
+ * Row type for GroupTokenHoldersBalance view table
+ */
+export interface GroupTokenHolderRow {
+    group: Address;
+    holder: Address;
+    totalBalance: bigint;
+    demurragedTotalBalance: bigint;
+    fractionOwnership: number;
+}
+/**
+ * Configuration for a cursor column in pagination
+ */
+export interface CursorColumn {
+    name: string;
+    sortOrder: 'ASC' | 'DESC';
+    toValue?: (value: any) => string | number | boolean;
+}
+/**
+ * Flexible paged result that works with both event-based and custom cursors
+ */
+export interface FlexiblePagedResult<TRow> {
+    limit: number;
+    size: number;
+    firstCursor?: Record<string, any>;
+    lastCursor?: Record<string, any>;
+    sortOrder: 'ASC' | 'DESC';
+    hasMore: boolean;
+    results: TRow[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAEvD;;;GAGG;AAEH;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;IACd,EAAE,EAAE,OAAO,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,OAAO,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sDAAsD;IACtD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wCAAwC;IACxC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,sBAAsB,EAAE,MAAM,CAAC;IAC/B,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,KAAK,GAAG,MAAM,CAAC;IAC1B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;CACrD;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB,CAAC,IAAI;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACjC,SAAS,EAAE,KAAK,GAAG,MAAM,CAAC;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,IAAI,EAAE,CAAC;CACjB"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils.d.ts

@@ -0,0 +1,27 @@
+import type { Address, FindPathParams } from '@aboutcircles/sdk-types';
+/**
+ * Normalize an address to lowercase (required by the indexer)
+ */
+export declare function normalizeAddress(address: Address): Address;
+/**
+ * Normalize an array of addresses to lowercase
+ */
+export declare function normalizeAddresses(addresses: Address[]): Address[];
+/**
+ * Convert an address to EIP-55 checksummed format
+ */
+export declare function checksumAddress(address: Address): Address;
+/**
+ * Recursively checksum all address strings in an object, array, or primitive value
+ */
+export declare function checksumAddresses<T>(value: T): T;
+/**
+ * Normalize and convert FindPathParams for RPC call
+ * Converts camelCase to PascalCase and bigint to human-readable numbers
+ */
+export declare function normalizeFindPathParams(params: FindPathParams): Record<string, unknown>;
+/**
+ * Convert string numeric values to bigint in an object
+ */
+export declare function parseStringsToBigInt<T extends Record<string, unknown>>(obj: T): T;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAoB,MAAM,yBAAyB,CAAC;AAGzF;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAE1D;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE,CAElE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAEzD;AAWD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CA6BhD;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAmBvF;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CA2BjF"}

package/dist/utils.js

@@ -0,0 +1,111 @@
+import { checksumAddress as toChecksumAddress } from '@aboutcircles/sdk-utils';
+/**
+ * Normalize an address to lowercase (required by the indexer)
+ */
+export function normalizeAddress(address) {
+    return address.toLowerCase();
+}
+/**
+ * Normalize an array of addresses to lowercase
+ */
+export function normalizeAddresses(addresses) {
+    return addresses.map(addr => normalizeAddress(addr));
+}
+/**
+ * Convert an address to EIP-55 checksummed format
+ */
+export function checksumAddress(address) {
+    return toChecksumAddress(address);
+}
+/**
+ * Detect if a value is an Ethereum address (40 hex chars, optionally prefixed with 0x)
+ */
+function isAddress(value) {
+    if (typeof value !== 'string')
+        return false;
+    const cleaned = value.replace('0x', '');
+    return cleaned.length === 40 && /^[0-9a-fA-F]{40}$/.test(cleaned);
+}
+/**
+ * Recursively checksum all address strings in an object, array, or primitive value
+ */
+export function checksumAddresses(value) {
+    // Handle null/undefined
+    if (value === null || value === undefined) {
+        return value;
+    }
+    // Handle address strings
+    if (isAddress(value)) {
+        return checksumAddress(value);
+    }
+    // Handle arrays
+    if (Array.isArray(value)) {
+        return value.map(item => checksumAddresses(item));
+    }
+    // Handle objects
+    if (typeof value === 'object' && value !== null) {
+        const result = {};
+        for (const key in value) {
+            if (Object.prototype.hasOwnProperty.call(value, key)) {
+                result[key] = checksumAddresses(value[key]);
+            }
+        }
+        return result;
+    }
+    // Return primitives as-is
+    return value;
+}
+/**
+ * Normalize and convert FindPathParams for RPC call
+ * Converts camelCase to PascalCase and bigint to human-readable numbers
+ */
+export function normalizeFindPathParams(params) {
+    return {
+        Source: normalizeAddress(params.from),
+        Sink: normalizeAddress(params.to),
+        TargetFlow: params.targetFlow.toString(),
+        WithWrap: params.useWrappedBalances,
+        FromTokens: params.fromTokens?.map(normalizeAddress),
+        ToTokens: params.toTokens?.map(normalizeAddress),
+        ExcludedFromTokens: params.excludeFromTokens?.map(normalizeAddress),
+        ExcludedToTokens: params.excludeToTokens?.map(normalizeAddress),
+        SimulatedBalances: params.simulatedBalances?.map((balance) => ({
+            Holder: normalizeAddress(balance.holder),
+            Token: normalizeAddress(balance.token),
+            Amount: balance.amount.toString(),
+            IsWrapped: balance.isWrapped,
+            IsStatic: balance.isStatic,
+        })),
+        MaxTransfers: params.maxTransfers,
+    };
+}
+/**
+ * Convert string numeric values to bigint in an object
+ */
+export function parseStringsToBigInt(obj) {
+    const result = {};
+    for (const key in obj) {
+        const value = obj[key];
+        if (value === null || value === undefined) {
+            result[key] = value;
+        }
+        else if (typeof value === 'string' && /^\d+$/.test(value)) {
+            // Convert numeric strings to bigint
+            result[key] = BigInt(value);
+        }
+        else if (typeof value === 'object' && !Array.isArray(value)) {
+            // Recursively process nested objects
+            result[key] = parseStringsToBigInt(value);
+        }
+        else if (Array.isArray(value)) {
+            // Process arrays
+            result[key] = value.map(item => typeof item === 'object' && item !== null
+                ? parseStringsToBigInt(item)
+                : item);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@aboutcircles/sdk-rpc",
+  "version": "0.1.0",
+  "description": "Circles RPC wrapper",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --format esm --splitting && tsc --emitDeclarationOnly",
+    "dev": "tsc --watch"
+  },
+  "dependencies": {
+    "@aboutcircles/sdk-types": "*",
+    "@aboutcircles/sdk-utils": "*"
+  },
+  "devDependencies": {
+    "@esbuild-kit/esm-loader": "^2.6.5",
+    "@types/bun": "^1.2.23",
+    "esbuild": "^0.25.10",
+    "typescript": "^5.0.4"
+  }
+}