@aboutcircles/sdk-rpc 0.1.28 → 0.1.30

package/dist/methods/invitation.js

@@ -1,25 +1,38 @@
 import { normalizeAddress, checksumAddresses } from '../utils.js';
 /**
  * Invitation RPC methods
+ *
+ * All methods delegate to dedicated RPC endpoints for server-side SQL optimization.
  */
 export class InvitationMethods {
     client;
     constructor(client) {
         this.client = client;
     }
-    transformQueryResponse(response) {
-        const { columns, rows } = response;
-        return rows.map((row) => {
-            const obj = {};
-            columns.forEach((col, index) => {
-                obj[col] = row[index];
-            });
-            return obj;
-        });
+    /**
+     * Get the invitation origin for an address — how they were invited to Circles
+     *
+     * @param address - The address of the invited avatar
+     * @returns Full invitation origin details or null if not registered
+     *
+     * @example
+     * ```typescript
+     * const origin = await rpc.invitation.getInvitationOrigin('0xde374ece6fa50e781e81aac78e811b33d16912c7');
+     * console.log(origin?.invitationType); // 'v2_standard', 'v2_escrow', 'v2_at_scale', 'v1_signup'
+     * console.log(origin?.inviter); // '0x...' or null
+     * ```
+     */
+    async getInvitationOrigin(address) {
+        const normalized = normalizeAddress(address);
+        const response = await this.client.call('circles_getInvitationOrigin', [normalized]);
+        return response ? checksumAddresses(response) : null;
     }
     /**
      * Get the avatar that invited a specific avatar
      *
+     * Uses `circles_getInvitationOrigin` for a single optimized query that checks
+     * all invitation mechanisms (at-scale, escrow, v2 standard, v1 signup).
+     *
      * @param address - The address of the invited avatar
      * @returns The address of the inviting avatar or undefined if not found
      *
@@ -30,38 +43,32 @@ export class InvitationMethods {
      * ```
      */
     async getInvitedBy(address) {
-        const normalized = normalizeAddress(address);
-        const results = await this.client.call('circles_query', [
-            {
-                Namespace: 'CrcV2',
-                Table: 'RegisterHuman',
-                Columns: ['inviter'],
-                Filter: [
-                    {
-                        Type: 'FilterPredicate',
-                        FilterType: 'Equals',
-                        Column: 'avatar',
-                        Value: normalized,
-                    },
-                ],
-                Order: [
-                    {
-                        Column: 'blockNumber',
-                        SortOrder: 'DESC',
-                    },
-                ],
-                Limit: 1,
-            },
-        ]);
-        if (results.length > 0) {
-            return checksumAddresses(results[0].inviter);
+        const origin = await this.getInvitationOrigin(address);
+        if (origin?.inviter) {
+            return checksumAddresses(origin.inviter);
         }
         return undefined;
     }
+    /**
+     * Get trust-based invitations (addresses that trust you with sufficient balance)
+     *
+     * Uses dedicated `circles_getTrustInvitations` endpoint.
+     *
+     * @param address - The address to check for trust invitations
+     * @param minimumBalance - Optional minimum balance threshold (as CRC string)
+     * @returns Array of trust invitations
+     */
+    async getTrustInvitations(address, minimumBalance) {
+        const normalized = normalizeAddress(address);
+        const response = await this.client.call('circles_getTrustInvitations', minimumBalance ? [normalized, minimumBalance] : [normalized]);
+        return checksumAddresses(response);
+    }
     /**
      * Get the list of avatars who have invited this avatar
      * Checks v2 trust relations and validates that inviters have enough balance
      *
+     * Uses the native RPC method for efficient server-side filtering and validation.
+     *
      * @param address - The address to check for invitations
      * @returns Array of avatar info for valid inviters
      *
@@ -71,73 +78,33 @@ export class InvitationMethods {
      * console.log(invitations); // Array of AvatarInfo
      * ```
      */
-    async getInvitations(address) {
+    async getInvitations(address, minimumBalance) {
+        const response = await this.getValidInviters(address, minimumBalance);
+        const inviters = response.results
+            .map((entry) => entry.avatarInfo)
+            .filter((info) => info !== undefined && info !== null);
+        return checksumAddresses(inviters);
+    }
+    /**
+     * Fetch valid inviters along with balances and avatar info
+     *
+     * @param address - Address to find inviters for
+     * @param minimumBalance - Optional minimum balance to filter inviters
+     * @returns Valid inviters response as provided by the RPC host
+     */
+    async getValidInviters(address, minimumBalance) {
         const normalized = normalizeAddress(address);
-        const MIN_TOKENS_REQUIRED = 96;
-        // Check if the avatar is still on v1
-        const avatarInfoResults = await this.client.call('circles_getAvatarInfoBatch', [[normalized]]);
-        const avatarInfo = avatarInfoResults.length > 0 ? avatarInfoResults[0] : undefined;
-        if (avatarInfo?.version === 2) {
-            // Already on v2, no invitations needed
-            return [];
-        }
-        // Get trust relations where others trust this avatar
-        const response = await this.client.call('circles_query', [
-            {
-                Namespace: 'V_Crc',
-                Table: 'TrustRelations',
-                Columns: ['truster', 'trustee'],
-                Filter: [
-                    {
-                        Type: 'Conjunction',
-                        ConjunctionType: 'And',
-                        Predicates: [
-                            {
-                                Type: 'FilterPredicate',
-                                FilterType: 'Equals',
-                                Column: 'version',
-                                Value: 2,
-                            },
-                            {
-                                Type: 'FilterPredicate',
-                                FilterType: 'Equals',
-                                Column: 'trustee',
-                                Value: normalized,
-                            },
-                        ],
-                    },
-                ],
-                Order: [],
-            },
-        ]);
-        const trustRelations = this.transformQueryResponse(response);
-        const v2Trusters = trustRelations.map((r) => r.truster);
-        if (v2Trusters.length === 0) {
-            return [];
-        }
-        // Get avatar info for all trusters
-        const trusterInfos = await this.client.call('circles_getAvatarInfoBatch', [v2Trusters]);
-        const humanInviters = [];
-        for (const trusterInfo of trusterInfos) {
-            // Only humans can invite other humans
-            if (!trusterInfo?.isHuman) {
-                continue;
-            }
-            // Check if the inviter has enough tokens
-            const balances = await this.client.call('circles_getTokenBalances', [trusterInfo.avatar]);
-            const inviterOwnToken = balances.find((b) => normalizeAddress(b.tokenAddress) === normalizeAddress(trusterInfo.avatar));
-            if (inviterOwnToken && inviterOwnToken.circles >= MIN_TOKENS_REQUIRED) {
-                humanInviters.push(trusterInfo);
-            }
-        }
-        return checksumAddresses(humanInviters);
+        const response = await this.client.call('circles_getValidInviters', minimumBalance ? [normalized, minimumBalance] : [normalized]);
+        return checksumAddresses(response);
     }
     /**
      * Get the list of accounts that were invited by a specific avatar
      *
+     * Uses dedicated `circles_getInvitationsFrom` endpoint with server-side SQL.
+     *
      * @param address - The address of the inviter
      * @param accepted - If true, returns accepted invitations; if false, returns pending invitations
-     * @returns Array of invited addresses
+     * @returns Enriched response with invited account info and avatar data
      *
      * @example
      * ```typescript
@@ -146,85 +113,84 @@ export class InvitationMethods {
      *   '0xde374ece6fa50e781e81aac78e811b33d16912c7',
      *   true
      * );
+     * console.log(accepted.results); // [{address, status: 'accepted', avatarInfo, ...}]
      *
      * // Get pending invitations
      * const pending = await rpc.invitation.getInvitationsFrom(
      *   '0xde374ece6fa50e781e81aac78e811b33d16912c7',
      *   false
      * );
+     * console.log(pending.results); // [{address, status: 'pending'}]
      * ```
      */
     async getInvitationsFrom(address, accepted = false) {
         const normalized = normalizeAddress(address);
-        if (accepted) {
-            // Query for accounts that have registered using this avatar as inviter
-            const response = await this.client.call('circles_query', [
-                {
-                    Namespace: 'CrcV2',
-                    Table: 'RegisterHuman',
-                    Columns: ['avatar'],
-                    Filter: [
-                        {
-                            Type: 'FilterPredicate',
-                            FilterType: 'Equals',
-                            Column: 'inviter',
-                            Value: normalized,
-                        },
-                    ],
-                    Order: [
-                        {
-                            Column: 'blockNumber',
-                            SortOrder: 'DESC',
-                        },
-                    ],
-                },
-            ]);
-            const results = this.transformQueryResponse(response);
-            const avatars = results.map((r) => r.avatar);
-            return checksumAddresses(avatars);
-        }
-        else {
-            // Find accounts that this avatar trusts without mutual trust
-            const response = await this.client.call('circles_query', [
-                {
-                    Namespace: 'V_Crc',
-                    Table: 'TrustRelations',
-                    Columns: ['trustee', 'truster'],
-                    Filter: [
-                        {
-                            Type: 'Conjunction',
-                            ConjunctionType: 'And',
-                            Predicates: [
-                                {
-                                    Type: 'FilterPredicate',
-                                    FilterType: 'Equals',
-                                    Column: 'version',
-                                    Value: 2,
-                                },
-                                {
-                                    Type: 'FilterPredicate',
-                                    FilterType: 'Equals',
-                                    Column: 'truster',
-                                    Value: normalized,
-                                },
-                            ],
-                        },
-                    ],
-                    Order: [],
-                },
-            ]);
-            const trustRelations = this.transformQueryResponse(response);
-            const v2Trusted = trustRelations.map((r) => r.trustee);
-            if (v2Trusted.length === 0) {
-                return [];
-            }
-            // Get avatar info for trusted accounts
-            const trustedAvatarsInfo = await this.client.call('circles_getAvatarInfoBatch', [v2Trusted]);
-            // Create a Set of registered avatars (filter out null values) - normalize for comparison
-            const registeredAvatarsSet = new Set(trustedAvatarsInfo.filter((a) => a !== null).map((a) => normalizeAddress(a.avatar)));
-            // Return only unregistered accounts (pending invitations)
-            const pending = v2Trusted.filter((addr) => !registeredAvatarsSet.has(normalizeAddress(addr)));
-            return checksumAddresses(pending);
-        }
+        const response = await this.client.call('circles_getInvitationsFrom', [normalized, accepted]);
+        return checksumAddresses(response);
+    }
+    /**
+     * Get escrow-based invitations for an address
+     *
+     * Uses dedicated `circles_getEscrowInvitations` endpoint which handles all filtering
+     * server-side (redeemed, revoked, refunded) in a single optimized SQL query.
+     *
+     * @param address - The address to check for escrow invitations
+     * @returns Array of active escrow invitations
+     *
+     * @example
+     * ```typescript
+     * const escrowInvites = await rpc.invitation.getEscrowInvitations('0xde374ece6fa50e781e81aac78e811b33d16912c7');
+     * console.log(escrowInvites); // Array of EscrowInvitation
+     * ```
+     */
+    async getEscrowInvitations(address) {
+        const normalized = normalizeAddress(address);
+        const response = await this.client.call('circles_getEscrowInvitations', [normalized]);
+        return checksumAddresses(response);
+    }
+    /**
+     * Get at-scale invitations for an address
+     *
+     * Uses dedicated `circles_getAtScaleInvitations` endpoint which checks for
+     * unclaimed pre-created accounts in a single optimized SQL query.
+     *
+     * @param address - The address to check for at-scale invitations
+     * @returns Array of at-scale invitations (unclaimed pre-created accounts)
+     *
+     * @example
+     * ```typescript
+     * const atScaleInvites = await rpc.invitation.getAtScaleInvitations('0xde374ece6fa50e781e81aac78e811b33d16912c7');
+     * console.log(atScaleInvites); // Array of AtScaleInvitation
+     * ```
+     */
+    async getAtScaleInvitations(address) {
+        const normalized = normalizeAddress(address);
+        const response = await this.client.call('circles_getAtScaleInvitations', [normalized]);
+        return checksumAddresses(response);
+    }
+    /**
+     * Get all invitations from all sources (trust, escrow, at-scale)
+     * This is the recommended method to use for getting a complete view of available invitations
+     *
+     * Uses the optimized `circles_getAllInvitations` RPC method which fetches all invitation
+     * types in a single round-trip with server-side SQL JOINs for efficiency.
+     *
+     * @param address - The address to check for invitations
+     * @param minimumBalance - Optional minimum balance for trust-based invitations
+     * @returns All invitations from all sources
+     *
+     * @example
+     * ```typescript
+     * const allInvites = await rpc.invitation.getAllInvitations('0xde374ece6fa50e781e81aac78e811b33d16912c7');
+     * console.log(`Trust invites: ${allInvites.trustInvitations.length}`);
+     * console.log(`Escrow invites: ${allInvites.escrowInvitations.length}`);
+     * console.log(`At-scale invites: ${allInvites.atScaleInvitations.length}`);
+     * ```
+     */
+    async getAllInvitations(address, minimumBalance) {
+        const normalized = normalizeAddress(address);
+        // Use the optimized RPC method that fetches all invitation types in a single call
+        const response = await this.client.call('circles_getAllInvitations', minimumBalance ? [normalized, minimumBalance] : [normalized]);
+        return checksumAddresses(response);
     }
 }

package/dist/methods/profile.d.ts

@@ -1,5 +1,5 @@
 import type { RpcClient } from '../client.js';
-import type { Address, Profile } from '@aboutcircles/sdk-types';
+import type { Address, Profile, ProfileView, ProfileSearchResponse } from '@aboutcircles/sdk-types';
 import type { SearchResultProfile } from '../types.js';
 /**
  * Profile RPC methods
@@ -91,9 +91,9 @@ export declare class ProfileMethods {
      *
      * @param query - Search query (address or username)
      * @param limit - Maximum number of results (default: 10)
-     * @param offset - Offset for pagination (default: 0)
+     * @param cursor - Pagination cursor from previous response (null for first page)
      * @param avatarTypes - Optional array of avatar types to filter by
-     * @returns Array of matching profiles, with exact address match (if valid) at the top
+     * @returns Search results with profiles and search type indicator
      *
      * @example
      * ```typescript
@@ -104,6 +104,14 @@ export declare class ProfileMethods {
      * const results = await rpc.profile.searchByAddressOrName('0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb', 20);
      * ```
      */
-    searchByAddressOrName(query: string, limit?: number, offset?: number, avatarTypes?: string[]): Promise<SearchResultProfile[]>;
+    searchByAddressOrName(query: string, limit?: number, cursor?: string | null, avatarTypes?: string[]): Promise<ProfileSearchResponse>;
+    /**
+     * Get a consolidated profile view
+     * Combines avatar info, profile data, trust stats, and balances in a single call
+     *
+     * @param address - The address to get the view for
+     * @returns Profile view data
+     */
+    getProfileView(address: Address): Promise<ProfileView>;
 }
 //# sourceMappingURL=profile.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"profile.d.ts","sourceRoot":"","sources":["../../src/methods/profile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAGvD;;GAEG;AACH,qBAAa,cAAc;IACb,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,SAAS;IAErC;;;;;;;;;;;OAWG;IACG,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAI3D;;;;;;;;;;;;;;OAcG;IACG,oBAAoB,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,GAAG,OAAO,CAAC,CAAC,OAAO,GAAG,IAAI,CAAC,EAAE,CAAC;IAOhF;;;;;;;;;;;OAWG;IACG,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAMpE;;;;;;;;;;;;;;OAcG;IACG,wBAAwB,CAAC,SAAS,EAAE,CAAC,OAAO,GAAG,IAAI,CAAC,EAAE,GAAG,OAAO,CAAC,CAAC,OAAO,GAAG,IAAI,CAAC,EAAE,CAAC;IAO1F;;;;;;;;;;;;;;;;;OAiBG;IACG,cAAc,CAClB,KAAK,EAAE,MAAM,EACb,KAAK,GAAE,MAAW,EAClB,MAAM,GAAE,MAAU,EAClB,WAAW,CAAC,EAAE,MAAM,EAAE,GACrB,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAYjC;;;;;;;;;;;;;;;;;;;OAmBG;IACG,qBAAqB,CACzB,KAAK,EAAE,MAAM,EACb,KAAK,GAAE,MAAW,EAClB,MAAM,GAAE,MAAU,EAClB,WAAW,CAAC,EAAE,MAAM,EAAE,GACrB,OAAO,CAAC,mBAAmB,EAAE,CAAC;CA8ClC"}
+{"version":3,"file":"profile.d.ts","sourceRoot":"","sources":["../../src/methods/profile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AACpG,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAGvD;;GAEG;AACH,qBAAa,cAAc;IACb,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,SAAS;IAErC;;;;;;;;;;;OAWG;IACG,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAI3D;;;;;;;;;;;;;;OAcG;IACG,oBAAoB,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,GAAG,OAAO,CAAC,CAAC,OAAO,GAAG,IAAI,CAAC,EAAE,CAAC;IAOhF;;;;;;;;;;;OAWG;IACG,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAMpE;;;;;;;;;;;;;;OAcG;IACG,wBAAwB,CAAC,SAAS,EAAE,CAAC,OAAO,GAAG,IAAI,CAAC,EAAE,GAAG,OAAO,CAAC,CAAC,OAAO,GAAG,IAAI,CAAC,EAAE,CAAC;IAO1F;;;;;;;;;;;;;;;;;OAiBG;IACG,cAAc,CAClB,KAAK,EAAE,MAAM,EACb,KAAK,GAAE,MAAW,EAClB,MAAM,GAAE,MAAU,EAClB,WAAW,CAAC,EAAE,MAAM,EAAE,GACrB,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAYjC;;;;;;;;;;;;;;;;;;;OAmBG;IACG,qBAAqB,CACzB,KAAK,EAAE,MAAM,EACb,KAAK,GAAE,MAAW,EAClB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,EACtB,WAAW,CAAC,EAAE,MAAM,EAAE,GACrB,OAAO,CAAC,qBAAqB,CAAC;IAMjC;;;;;;OAMG;IACG,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,WAAW,CAAC;CAK7D"}

package/dist/methods/profile.js

@@ -108,9 +108,9 @@ export class ProfileMethods {
      *
      * @param query - Search query (address or username)
      * @param limit - Maximum number of results (default: 10)
-     * @param offset - Offset for pagination (default: 0)
+     * @param cursor - Pagination cursor from previous response (null for first page)
      * @param avatarTypes - Optional array of avatar types to filter by
-     * @returns Array of matching profiles, with exact address match (if valid) at the top
+     * @returns Search results with profiles and search type indicator
      *
      * @example
      * ```typescript
@@ -121,46 +121,19 @@ export class ProfileMethods {
      * const results = await rpc.profile.searchByAddressOrName('0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb', 20);
      * ```
      */
-    async searchByAddressOrName(query, limit = 10, offset = 0, avatarTypes) {
-        const results = [];
-        // Check if query is a valid address
-        const isAddress = /^0x[a-fA-F0-9]{40}$/.test(query);
-        if (isAddress) {
-            // Try to get profile by address first
-            try {
-                const profile = await this.getProfileByAddress(query);
-                if (profile) {
-                    // Convert Profile to SearchResultProfile by adding address
-                    const searchResult = {
-                        ...profile,
-                        address: query
-                    };
-                    // Check if profile matches avatar type filter
-                    if (!avatarTypes || !searchResult.avatarType || avatarTypes.includes(searchResult.avatarType)) {
-                        results.push(searchResult);
-                    }
-                }
-            }
-            catch (error) {
-                console.warn('Failed to get profile by address:', error);
-            }
-        }
-        // Always search by text as well
-        try {
-            const textResults = await this.searchProfiles(query, limit, offset, avatarTypes);
-            // If we already added an address match, filter it out from text results to avoid duplicates
-            if (isAddress && results.length > 0) {
-                const addressLower = query.toLowerCase();
-                const filteredResults = textResults.filter(p => p.address?.toLowerCase() !== addressLower);
-                results.push(...filteredResults);
-            }
-            else {
-                results.push(...textResults);
-            }
-        }
-        catch (error) {
-            console.warn('Failed to search profiles by text:', error);
-        }
-        return results.slice(0, limit);
+    async searchByAddressOrName(query, limit = 10, cursor, avatarTypes) {
+        return this.client.call('circles_searchProfileByAddressOrName', avatarTypes ? [query, limit, cursor ?? null, avatarTypes] : [query, limit, cursor ?? null]);
+    }
+    /**
+     * Get a consolidated profile view
+     * Combines avatar info, profile data, trust stats, and balances in a single call
+     *
+     * @param address - The address to get the view for
+     * @returns Profile view data
+     */
+    async getProfileView(address) {
+        return this.client.call('circles_getProfileView', [
+            normalizeAddress(address),
+        ]);
     }
 }

package/dist/methods/query.d.ts

@@ -1,5 +1,21 @@
 import type { RpcClient } from '../client.js';
 import type { QueryParams, TableInfo, EventType } from '@aboutcircles/sdk-types';
+/**
+ * Filter predicate for advanced event queries
+ */
+export interface FilterPredicate {
+    column: string;
+    filterType: string;
+    value: string;
+}
+/**
+ * Paginated events response
+ */
+export interface PagedEventsResponse<T = unknown> {
+    events: T[];
+    hasMore: boolean;
+    nextCursor: string | null;
+}
 /**
  * Query and table RPC methods
  */
@@ -54,26 +70,39 @@ export declare class QueryMethods {
      */
     tables(): Promise<TableInfo[]>;
     /**
-     * Query events of specific types within a block range
+     * Query events of specific types within a block range with pagination support.
      *
+     * @param address - Optional address filter (null for all addresses)
      * @param fromBlock - Starting block number (null for genesis)
      * @param toBlock - Ending block number (null for latest)
      * @param eventTypes - Array of event types to filter (null for all)
-     * @param address - Optional address filter
-     * @param includeTransactionData - Whether to include transaction data
-     * @returns Array of events
+     * @param filterPredicates - Advanced filter predicates (null for none)
+     * @param sortAscending - Sort order (default: false = descending)
+     * @param limit - Maximum events to return (default: 100, max: 1000)
+     * @param cursor - Pagination cursor from previous response (null for first page)
+     * @returns Paginated events response with events array, hasMore flag, and nextCursor
      *
      * @example
      * ```typescript
-     * const events = await rpc.query.events(
+     * // Basic usage - get first page of events for an address
+     * const result = await rpc.query.events(
+     *   '0xde374ece6fa50e781e81aac78e811b33d16912c7',
      *   38000000,
      *   null,
-     *   ['CrcV1_Trust'],
-     *   null,
-     *   false
+     *   ['CrcV1_Trust']
      * );
+     * console.log(result.events);
+     * console.log(result.hasMore, result.nextCursor);
+     *
+     * // Paginate through results
+     * let cursor: string | null = null;
+     * do {
+     *   const page = await rpc.query.events(address, fromBlock, null, null, null, false, 100, cursor);
+     *   console.log(page.events);
+     *   cursor = page.nextCursor;
+     * } while (cursor);
      * ```
      */
-    events<T = unknown>(fromBlock: number | null, toBlock: number | null, eventTypes?: EventType[] | null, address?: string | null, includeTransactionData?: boolean): Promise<T[]>;
+    events<T = unknown>(address?: string | null, fromBlock?: number | null, toBlock?: number | null, eventTypes?: EventType[] | null, filterPredicates?: FilterPredicate[] | null, sortAscending?: boolean, limit?: number, cursor?: string | null): Promise<PagedEventsResponse<T>>;
 }
 //# sourceMappingURL=query.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/methods/query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAGjF;;GAEG;AACH,qBAAa,YAAY;IACX,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,SAAS;IAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACG,KAAK,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAK3D;;;;;;;;;;OAUG;IACG,MAAM,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAIpC;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,MAAM,CAAC,CAAC,GAAG,OAAO,EACtB,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,OAAO,EAAE,MAAM,GAAG,IAAI,EACtB,UAAU,GAAE,SAAS,EAAE,GAAG,IAAW,EACrC,OAAO,GAAE,MAAM,GAAG,IAAW,EAC7B,sBAAsB,GAAE,OAAe,GACtC,OAAO,CAAC,CAAC,EAAE,CAAC;CAOhB"}
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/methods/query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,EAAqC,MAAM,yBAAyB,CAAC;AAGpH;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB,CAAC,CAAC,GAAG,OAAO;IAC9C,MAAM,EAAE,CAAC,EAAE,CAAC;IACZ,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;GAEG;AACH,qBAAa,YAAY;IACX,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,SAAS;IAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACG,KAAK,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAa3D;;;;;;;;;;OAUG;IACG,MAAM,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAIpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACG,MAAM,CAAC,CAAC,GAAG,OAAO,EACtB,OAAO,GAAE,MAAM,GAAG,IAAW,EAC7B,SAAS,GAAE,MAAM,GAAG,IAAW,EAC/B,OAAO,GAAE,MAAM,GAAG,IAAW,EAC7B,UAAU,GAAE,SAAS,EAAE,GAAG,IAAW,EACrC,gBAAgB,GAAE,eAAe,EAAE,GAAG,IAAW,EACjD,aAAa,GAAE,OAAe,EAC9B,KAAK,GAAE,MAAY,EACnB,MAAM,GAAE,MAAM,GAAG,IAAW,GAC3B,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC;CAYnC"}

package/dist/methods/query.js

@@ -42,8 +42,16 @@ export class QueryMethods {
      * ```
      */
     async query(params) {
-        const result = await this.client.call('circles_query', [params]);
-        return checksumAddresses(result);
+        const response = await this.client.call('circles_query', [params]);
+        const { columns, rows } = response;
+        const objects = rows.map(row => {
+            const obj = {};
+            columns.forEach((col, index) => {
+                obj[col] = row[index];
+            });
+            return obj;
+        });
+        return checksumAddresses(objects);
     }
     /**
      * Return all available namespaces and tables which can be queried
@@ -60,28 +68,45 @@ export class QueryMethods {
         return this.client.call('circles_tables', []);
     }
     /**
-     * Query events of specific types within a block range
+     * Query events of specific types within a block range with pagination support.
      *
+     * @param address - Optional address filter (null for all addresses)
      * @param fromBlock - Starting block number (null for genesis)
      * @param toBlock - Ending block number (null for latest)
      * @param eventTypes - Array of event types to filter (null for all)
-     * @param address - Optional address filter
-     * @param includeTransactionData - Whether to include transaction data
-     * @returns Array of events
+     * @param filterPredicates - Advanced filter predicates (null for none)
+     * @param sortAscending - Sort order (default: false = descending)
+     * @param limit - Maximum events to return (default: 100, max: 1000)
+     * @param cursor - Pagination cursor from previous response (null for first page)
+     * @returns Paginated events response with events array, hasMore flag, and nextCursor
      *
      * @example
      * ```typescript
-     * const events = await rpc.query.events(
+     * // Basic usage - get first page of events for an address
+     * const result = await rpc.query.events(
+     *   '0xde374ece6fa50e781e81aac78e811b33d16912c7',
      *   38000000,
      *   null,
-     *   ['CrcV1_Trust'],
-     *   null,
-     *   false
+     *   ['CrcV1_Trust']
      * );
+     * console.log(result.events);
+     * console.log(result.hasMore, result.nextCursor);
+     *
+     * // Paginate through results
+     * let cursor: string | null = null;
+     * do {
+     *   const page = await rpc.query.events(address, fromBlock, null, null, null, false, 100, cursor);
+     *   console.log(page.events);
+     *   cursor = page.nextCursor;
+     * } while (cursor);
      * ```
      */
-    async events(fromBlock, toBlock, eventTypes = null, address = null, includeTransactionData = false) {
-        const result = await this.client.call('circles_events', [fromBlock, toBlock, eventTypes, address, includeTransactionData]);
-        return checksumAddresses(result);
+    async events(address = null, fromBlock = null, toBlock = null, eventTypes = null, filterPredicates = null, sortAscending = false, limit = 100, cursor = null) {
+        const result = await this.client.call('circles_events_paginated', [address, fromBlock, toBlock, eventTypes, filterPredicates, sortAscending, limit, cursor]);
+        return {
+            events: checksumAddresses(result.events),
+            hasMore: result.hasMore,
+            nextCursor: result.nextCursor
+        };
     }
 }