@aboutcircles/sdk-rpc 0.1.0

package/dist/methods/avatar.d.ts

@@ -0,0 +1,51 @@
+import type { RpcClient } from '../client';
+import type { Address, AvatarInfo, NetworkSnapshot } from '@aboutcircles/sdk-types';
+/**
+ * Avatar and network RPC methods
+ */
+export declare class AvatarMethods {
+    private client;
+    constructor(client: RpcClient);
+    /**
+     * Get information about a specific avatar
+     *
+     * @param address - The avatar address to query
+     * @returns Avatar information
+     *
+     * @example
+     * ```typescript
+     * const info = await rpc.avatar.getAvatarInfo('0xde374ece6fa50e781e81aac78e811b33d16912c7');
+     * console.log(info);
+     * ```
+     */
+    getAvatarInfo(address: Address): Promise<AvatarInfo | undefined>;
+    /**
+     * Get information about multiple avatars in batch
+     *
+     * @param addresses - Array of avatar addresses to query
+     * @returns Array of avatar information objects
+     *
+     * @example
+     * ```typescript
+     * const infos = await rpc.avatar.getAvatarInfoBatch([
+     *   '0xde374ece6fa50e781e81aac78e811b33d16912c7',
+     *   '0xc3a1428c04c426cdf513c6fc8e09f55ddaf50cd7'
+     * ]);
+     * ```
+     */
+    getAvatarInfoBatch(addresses: Address[]): Promise<AvatarInfo[]>;
+    /**
+     * Download a full snapshot of the Circles network state
+     * (current trust relations and balances)
+     *
+     * @returns Network snapshot with trust relations and balances
+     *
+     * @example
+     * ```typescript
+     * const snapshot = await rpc.avatar.getNetworkSnapshot();
+     * console.log(snapshot);
+     * ```
+     */
+    getNetworkSnapshot(): Promise<NetworkSnapshot>;
+}
+//# sourceMappingURL=avatar.d.ts.map

package/dist/methods/avatar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"avatar.d.ts","sourceRoot":"","sources":["../../src/methods/avatar.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAGpF;;GAEG;AACH,qBAAa,aAAa;IACZ,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,SAAS;IAErC;;;;;;;;;;;OAWG;IACG,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAKtE;;;;;;;;;;;;;OAaG;IACG,kBAAkB,CAAC,SAAS,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAcrE;;;;;;;;;;;OAWG;IACG,kBAAkB,IAAI,OAAO,CAAC,eAAe,CAAC;CAOrD"}

package/dist/methods/avatar.js

@@ -0,0 +1,64 @@
+import { normalizeAddress, checksumAddresses } from '../utils';
+/**
+ * Avatar and network RPC methods
+ */
+export class AvatarMethods {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Get information about a specific avatar
+     *
+     * @param address - The avatar address to query
+     * @returns Avatar information
+     *
+     * @example
+     * ```typescript
+     * const info = await rpc.avatar.getAvatarInfo('0xde374ece6fa50e781e81aac78e811b33d16912c7');
+     * console.log(info);
+     * ```
+     */
+    async getAvatarInfo(address) {
+        const results = await this.getAvatarInfoBatch([address]);
+        return results.length > 0 ? results[0] : undefined;
+    }
+    /**
+     * Get information about multiple avatars in batch
+     *
+     * @param addresses - Array of avatar addresses to query
+     * @returns Array of avatar information objects
+     *
+     * @example
+     * ```typescript
+     * const infos = await rpc.avatar.getAvatarInfoBatch([
+     *   '0xde374ece6fa50e781e81aac78e811b33d16912c7',
+     *   '0xc3a1428c04c426cdf513c6fc8e09f55ddaf50cd7'
+     * ]);
+     * ```
+     */
+    async getAvatarInfoBatch(addresses) {
+        if (addresses.length === 0) {
+            return [];
+        }
+        const normalizedAddresses = addresses.map(addr => normalizeAddress(addr));
+        const result = await this.client.call('circles_getAvatarInfoBatch', [normalizedAddresses]);
+        return checksumAddresses(result);
+    }
+    /**
+     * Download a full snapshot of the Circles network state
+     * (current trust relations and balances)
+     *
+     * @returns Network snapshot with trust relations and balances
+     *
+     * @example
+     * ```typescript
+     * const snapshot = await rpc.avatar.getNetworkSnapshot();
+     * console.log(snapshot);
+     * ```
+     */
+    async getNetworkSnapshot() {
+        const result = await this.client.call('circles_getNetworkSnapshot', []);
+        return checksumAddresses(result);
+    }
+}

package/dist/methods/balance.d.ts

@@ -0,0 +1,37 @@
+import type { RpcClient } from '../client';
+import type { Address, TokenBalance } from '@aboutcircles/sdk-types';
+/**
+ * Balance query RPC methods
+ */
+export declare class BalanceMethods {
+    private client;
+    constructor(client: RpcClient);
+    /**
+     * Get the total v2 Circles balance of an account
+     *
+     * @param address - The avatar address to query
+     * @param asTimeCircles - Whether to return balance as TimeCircles (default: true)
+     * @returns The total v2 balance in attoCircles (10^18 per Circle) as bigint
+     *
+     * @example
+     * ```typescript
+     * const balance = await rpc.balance.getTotalBalance('0xcadd4ea3bcc361fc4af2387937d7417be8d7dfc2');
+     * console.log(balance); // 1000000000000000000n (1 Circle in attoCircles)
+     * ```
+     */
+    getTotalBalance(address: Address, asTimeCircles?: boolean): Promise<bigint>;
+    /**
+     * Query the balance breakdown of a specific avatar address
+     *
+     * @param address - The avatar address to query
+     * @returns Array of token balances (amounts as bigint)
+     *
+     * @example
+     * ```typescript
+     * const balances = await rpc.balance.getTokenBalances('0x7cadf434b692ca029d950607a4b3f139c30d4e98');
+     * console.log(balances);
+     * ```
+     */
+    getTokenBalances(address: Address): Promise<TokenBalance[]>;
+}
+//# sourceMappingURL=balance.d.ts.map

package/dist/methods/balance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"balance.d.ts","sourceRoot":"","sources":["../../src/methods/balance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAIrE;;GAEG;AACH,qBAAa,cAAc;IACb,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,SAAS;IAErC;;;;;;;;;;;;OAYG;IACG,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,aAAa,GAAE,OAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IAQvF;;;;;;;;;;;OAWG;IACG,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;CAOlE"}

package/dist/methods/balance.js

@@ -0,0 +1,50 @@
+import { normalizeAddress, parseStringsToBigInt, checksumAddresses } from '../utils';
+import { CirclesConverter } from '@aboutcircles/sdk-utils';
+/**
+ * Balance query RPC methods
+ */
+export class BalanceMethods {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Get the total v2 Circles balance of an account
+     *
+     * @param address - The avatar address to query
+     * @param asTimeCircles - Whether to return balance as TimeCircles (default: true)
+     * @returns The total v2 balance in attoCircles (10^18 per Circle) as bigint
+     *
+     * @example
+     * ```typescript
+     * const balance = await rpc.balance.getTotalBalance('0xcadd4ea3bcc361fc4af2387937d7417be8d7dfc2');
+     * console.log(balance); // 1000000000000000000n (1 Circle in attoCircles)
+     * ```
+     */
+    async getTotalBalance(address, asTimeCircles = true) {
+        const result = await this.client.call('circlesV2_getTotalBalance', [
+            normalizeAddress(address),
+            asTimeCircles,
+        ]);
+        return CirclesConverter.circlesToAttoCircles(result);
+    }
+    /**
+     * Query the balance breakdown of a specific avatar address
+     *
+     * @param address - The avatar address to query
+     * @returns Array of token balances (amounts as bigint)
+     *
+     * @example
+     * ```typescript
+     * const balances = await rpc.balance.getTokenBalances('0x7cadf434b692ca029d950607a4b3f139c30d4e98');
+     * console.log(balances);
+     * ```
+     */
+    async getTokenBalances(address) {
+        const result = await this.client.call('circles_getTokenBalances', [
+            normalizeAddress(address),
+        ]);
+        const parsed = result.map(item => parseStringsToBigInt(item));
+        return checksumAddresses(parsed);
+    }
+}

package/dist/methods/group.d.ts

@@ -0,0 +1,145 @@
+import type { RpcClient } from '../client';
+import type { Address, GroupRow, GroupMembershipRow, GroupQueryParams } from '@aboutcircles/sdk-types';
+import type { GroupTokenHolderRow } from '../types';
+import { PagedQuery } from '../pagedQuery';
+/**
+ * Group query RPC methods
+ */
+export declare class GroupMethods {
+    private client;
+    constructor(client: RpcClient);
+    /**
+     * Find groups with optional filters
+     *
+     * This is a convenience method that fetches all pages using cursor-based pagination
+     * and returns the combined results up to the specified limit.
+     *
+     * @param limit - Maximum number of groups to return (default: 50)
+     * @param params - Optional query parameters to filter groups
+     * @returns Array of group rows
+     *
+     * @example
+     * ```typescript
+     * // Find all groups
+     * const allGroups = await rpc.group.findGroups(50);
+     *
+     * // Find groups by name prefix
+     * const groups = await rpc.group.findGroups(50, {
+     *   nameStartsWith: 'Community'
+     * });
+     *
+     * // Find groups by owner (single)
+     * const myGroups = await rpc.group.findGroups(50, {
+     *   ownerIn: ['0xde374ece6fa50e781e81aac78e811b33d16912c7']
+     * });
+     *
+     * // Find groups by multiple owners (OR query)
+     * const multiOwnerGroups = await rpc.group.findGroups(50, {
+     *   ownerIn: ['0xOwner1...', '0xOwner2...']
+     * });
+     * ```
+     */
+    findGroups(limit?: number, params?: GroupQueryParams): Promise<GroupRow[]>;
+    /**
+     * Get group memberships for an avatar using cursor-based pagination
+     *
+     * @param avatar - Avatar address to query group memberships for
+     * @param limit - Number of memberships per page (default: 50)
+     * @param sortOrder - Sort order for results (default: 'DESC')
+     * @returns PagedQuery instance for iterating through memberships
+     *
+     * @example
+     * ```typescript
+     * const query = rpc.group.getGroupMemberships(
+     *   '0xde374ece6fa50e781e81aac78e811b33d16912c7',
+     *   50
+     * );
+     * await query.queryNextPage();
+     * console.log(query.currentPage.results);
+     * ```
+     */
+    getGroupMemberships(avatar: Address, limit?: number, sortOrder?: 'ASC' | 'DESC'): PagedQuery<GroupMembershipRow>;
+    /**
+     * Get holders of a group token using cursor-based pagination
+     *
+     * Returns a PagedQuery instance that can be used to fetch holders page by page.
+     * Results are ordered by totalBalance DESC (highest first), with holder address as tie-breaker.
+     *
+     * Note: Pagination uses holder address as cursor because totalBalance (BigInt) values
+     * cannot be reliably passed through JSON-RPC filters. This means pagination boundaries
+     * are based on holder addresses, not balances.
+     *
+     * @param groupAddress - The address of the group token
+     * @param limit - Number of holders per page (default: 100)
+     * @returns PagedQuery instance for iterating through group token holders
+     *
+     * @example
+     * ```typescript
+     * const query = rpc.group.getGroupHolders('0xGroupAddress...', 50);
+     *
+     * // Get first page (ordered by totalBalance DESC)
+     * await query.queryNextPage();
+     * console.log(query.currentPage.results[0]); // Holder with highest balance
+     *
+     * // Get next page if available
+     * if (query.currentPage.hasMore) {
+     *   await query.queryNextPage();
+     * }
+     * ```
+     */
+    getGroupHolders(groupAddress: Address, limit?: number): PagedQuery<GroupTokenHolderRow>;
+    /**
+     * Get members of a group using cursor-based pagination
+     *
+     * Returns a PagedQuery instance that can be used to fetch members page by page
+     * using cursor-based pagination.
+     *
+     * @param groupAddress - The address of the group to query members for
+     * @param limit - Number of members per page (default: 100)
+     * @param sortOrder - Sort order for results (default: 'DESC')
+     * @returns PagedQuery instance for iterating through group members
+     *
+     * @example
+     * ```typescript
+     * const query = rpc.group.getGroupMembers('0xGroupAddress...', 100);
+     *
+     * // Get first page
+     * await query.queryNextPage();
+     * console.log(query.currentPage.results);
+     *
+     * // Get next page if available
+     * if (query.currentPage.hasMore) {
+     *   await query.queryNextPage();
+     *   console.log(query.currentPage.results);
+     * }
+     * ```
+     */
+    getGroupMembers(groupAddress: Address, limit?: number, sortOrder?: 'ASC' | 'DESC'): PagedQuery<GroupMembershipRow>;
+    /**
+     * Get groups using cursor-based pagination
+     *
+     * Returns a PagedQuery instance that can be used to fetch groups page by page
+     * using cursor-based pagination.
+     *
+     * @param limit - Number of groups per page (default: 50)
+     * @param params - Optional query parameters to filter groups
+     * @param sortOrder - Sort order for results (default: 'DESC')
+     * @returns PagedQuery instance for iterating through groups
+     *
+     * @example
+     * ```typescript
+     * // Query all groups
+     * const query = rpc.group.getGroups(50);
+     *
+     * // Query groups by owner(s)
+     * const myGroupsQuery = rpc.group.getGroups(50, {
+     *   ownerIn: ['0xMyAddress...']
+     * });
+     *
+     * await myGroupsQuery.queryNextPage();
+     * console.log(myGroupsQuery.currentPage.results);
+     * ```
+     */
+    getGroups(limit?: number, params?: GroupQueryParams, sortOrder?: 'ASC' | 'DESC'): PagedQuery<GroupRow>;
+}
+//# sourceMappingURL=group.d.ts.map

package/dist/methods/group.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"group.d.ts","sourceRoot":"","sources":["../../src/methods/group.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,kBAAkB,EAAE,gBAAgB,EAAU,MAAM,yBAAyB,CAAC;AAC/G,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAEpD,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C;;GAEG;AACH,qBAAa,YAAY;IACX,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,SAAS;IAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACG,UAAU,CACd,KAAK,GAAE,MAAW,EAClB,MAAM,CAAC,EAAE,gBAAgB,GACxB,OAAO,CAAC,QAAQ,EAAE,CAAC;IAwBtB;;;;;;;;;;;;;;;;;OAiBG;IACH,mBAAmB,CACjB,MAAM,EAAE,OAAO,EACf,KAAK,GAAE,MAAW,EAClB,SAAS,GAAE,KAAK,GAAG,MAAe,GACjC,UAAU,CAAC,kBAAkB,CAAC;IAiCjC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,eAAe,CACb,YAAY,EAAE,OAAO,EACrB,KAAK,GAAE,MAAY,GAClB,UAAU,CAAC,mBAAmB,CAAC;IAuClC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,eAAe,CACb,YAAY,EAAE,OAAO,EACrB,KAAK,GAAE,MAAY,EACnB,SAAS,GAAE,KAAK,GAAG,MAAe,GACjC,UAAU,CAAC,kBAAkB,CAAC;IAiCjC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,SAAS,CACP,KAAK,GAAE,MAAW,EAClB,MAAM,CAAC,EAAE,gBAAgB,EACzB,SAAS,GAAE,KAAK,GAAG,MAAe,GACjC,UAAU,CAAC,QAAQ,CAAC;CAiJxB"}