@aboutcircles/sdk-rpc 0.1.0

package/dist/methods/group.js

@@ -0,0 +1,380 @@
+import { normalizeAddress, checksumAddresses } from '../utils';
+import { PagedQuery } from '../pagedQuery';
+/**
+ * Group query RPC methods
+ */
+export class GroupMethods {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * 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...']
+     * });
+     * ```
+     */
+    async findGroups(limit = 50, params) {
+        // Create the paged query
+        const query = this.getGroups(limit, params, 'DESC');
+        const results = [];
+        // Fetch all pages up to the limit
+        while (await query.queryNextPage()) {
+            results.push(...query.currentPage.results);
+            // If we have enough results, break
+            if (results.length >= limit) {
+                break;
+            }
+            // If no more pages, break
+            if (!query.currentPage.hasMore) {
+                break;
+            }
+        }
+        // Apply limit
+        return results.slice(0, limit);
+    }
+    /**
+     * 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, limit = 50, sortOrder = 'DESC') {
+        const normalized = normalizeAddress(avatar);
+        return new PagedQuery(this.client, {
+            namespace: 'V_CrcV2',
+            table: 'GroupMemberships',
+            sortOrder,
+            columns: [
+                'blockNumber',
+                'timestamp',
+                'transactionIndex',
+                'logIndex',
+                'transactionHash',
+                'group',
+                'member',
+                'expiryTime',
+            ],
+            filter: [
+                {
+                    Type: 'FilterPredicate',
+                    FilterType: 'Equals',
+                    Column: 'member',
+                    Value: normalized,
+                },
+            ],
+            limit,
+        }, (row) => checksumAddresses(row));
+    }
+    /**
+     * 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, limit = 100) {
+        const normalized = normalizeAddress(groupAddress);
+        return new PagedQuery(this.client, {
+            namespace: 'V_CrcV2',
+            table: 'GroupTokenHoldersBalance',
+            sortOrder: 'DESC',
+            columns: ['group', 'holder', 'totalBalance', 'demurragedTotalBalance', 'fractionOwnership'],
+            cursorColumns: [
+                {
+                    name: 'holder',
+                    sortOrder: 'ASC', // Use holder for cursor-based pagination
+                },
+            ],
+            orderColumns: [
+                { Column: 'totalBalance', SortOrder: 'DESC' },
+                { Column: 'holder', SortOrder: 'ASC' },
+            ],
+            filter: [
+                {
+                    Type: 'FilterPredicate',
+                    FilterType: 'Equals',
+                    Column: 'group',
+                    Value: normalized,
+                },
+            ],
+            limit,
+            rowTransformer: (row) => {
+                // Convert string values to bigint for specific fields
+                const transformed = {
+                    ...row,
+                    totalBalance: BigInt(row.totalBalance),
+                    demurragedTotalBalance: BigInt(row.demurragedTotalBalance),
+                };
+                return checksumAddresses(transformed);
+            },
+        });
+    }
+    /**
+     * 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, limit = 100, sortOrder = 'DESC') {
+        const normalized = normalizeAddress(groupAddress);
+        return new PagedQuery(this.client, {
+            namespace: 'V_CrcV2',
+            table: 'GroupMemberships',
+            sortOrder,
+            columns: [
+                'blockNumber',
+                'timestamp',
+                'transactionIndex',
+                'logIndex',
+                'transactionHash',
+                'group',
+                'member',
+                'expiryTime',
+            ],
+            filter: [
+                {
+                    Type: 'FilterPredicate',
+                    FilterType: 'Equals',
+                    Column: 'group',
+                    Value: normalized,
+                },
+            ],
+            limit,
+        }, (row) => checksumAddresses(row));
+    }
+    /**
+     * 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 = 50, params, sortOrder = 'DESC') {
+        const filter = [];
+        if (params) {
+            if (params.nameStartsWith) {
+                filter.push({
+                    Type: 'FilterPredicate',
+                    FilterType: 'Like',
+                    Column: 'name',
+                    Value: params.nameStartsWith + '%',
+                });
+            }
+            if (params.symbolStartsWith) {
+                filter.push({
+                    Type: 'FilterPredicate',
+                    FilterType: 'Like',
+                    Column: 'symbol',
+                    Value: params.symbolStartsWith + '%',
+                });
+            }
+            if (params.groupAddressIn && params.groupAddressIn.length > 0) {
+                // Create an OR conjunction for matching any of the group addresses
+                const addressPredicates = params.groupAddressIn.map((addr) => ({
+                    Type: 'FilterPredicate',
+                    FilterType: 'Equals',
+                    Column: 'group',
+                    Value: normalizeAddress(addr),
+                }));
+                if (addressPredicates.length === 1) {
+                    filter.push(addressPredicates[0]);
+                }
+                else {
+                    filter.push({
+                        Type: 'Conjunction',
+                        ConjunctionType: 'Or',
+                        Predicates: addressPredicates,
+                    });
+                }
+            }
+            if (params.groupTypeIn && params.groupTypeIn.length > 0) {
+                // Create an OR conjunction for matching any of the group types
+                const typePredicates = params.groupTypeIn.map((type) => ({
+                    Type: 'FilterPredicate',
+                    FilterType: 'Equals',
+                    Column: 'type',
+                    Value: type,
+                }));
+                if (typePredicates.length === 1) {
+                    filter.push(typePredicates[0]);
+                }
+                else {
+                    filter.push({
+                        Type: 'Conjunction',
+                        ConjunctionType: 'Or',
+                        Predicates: typePredicates,
+                    });
+                }
+            }
+            if (params.ownerIn && params.ownerIn.length > 0) {
+                // Create an OR conjunction for matching any of the owners
+                const ownerPredicates = params.ownerIn.map((addr) => ({
+                    Type: 'FilterPredicate',
+                    FilterType: 'Equals',
+                    Column: 'owner',
+                    Value: normalizeAddress(addr),
+                }));
+                if (ownerPredicates.length === 1) {
+                    filter.push(ownerPredicates[0]);
+                }
+                else {
+                    filter.push({
+                        Type: 'Conjunction',
+                        ConjunctionType: 'Or',
+                        Predicates: ownerPredicates,
+                    });
+                }
+            }
+            if (params.mintHandlerEquals) {
+                filter.push({
+                    Type: 'FilterPredicate',
+                    FilterType: 'Equals',
+                    Column: 'mintHandler',
+                    Value: normalizeAddress(params.mintHandlerEquals),
+                });
+            }
+            if (params.treasuryEquals) {
+                filter.push({
+                    Type: 'FilterPredicate',
+                    FilterType: 'Equals',
+                    Column: 'treasury',
+                    Value: normalizeAddress(params.treasuryEquals),
+                });
+            }
+        }
+        const finalFilter = filter.length > 1
+            ? [
+                {
+                    Type: 'Conjunction',
+                    ConjunctionType: 'And',
+                    Predicates: filter,
+                },
+            ]
+            : filter;
+        return new PagedQuery(this.client, {
+            namespace: 'V_CrcV2',
+            table: 'Groups',
+            sortOrder,
+            columns: [
+                'blockNumber',
+                'timestamp',
+                'transactionIndex',
+                'logIndex',
+                'transactionHash',
+                'group',
+                'type',
+                'owner',
+                'mintPolicy',
+                'mintHandler',
+                'treasury',
+                'service',
+                'feeCollection',
+                'memberCount',
+                'name',
+                'symbol',
+                'cidV0Digest',
+                'erc20WrapperDemurraged',
+                'erc20WrapperStatic',
+            ],
+            filter: finalFilter,
+            limit,
+        }, (row) => checksumAddresses(row));
+    }
+}

package/dist/methods/index.d.ts

@@ -0,0 +1,11 @@
+export { PathfinderMethods } from './pathfinder';
+export { QueryMethods } from './query';
+export { TrustMethods } from './trust';
+export { BalanceMethods } from './balance';
+export { AvatarMethods } from './avatar';
+export { ProfileMethods } from './profile';
+export { TokenMethods } from './token';
+export { InvitationMethods } from './invitation';
+export { TransactionMethods } from './transaction';
+export { GroupMethods } from './group';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/methods/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC"}

package/dist/methods/index.js

@@ -0,0 +1,10 @@
+export { PathfinderMethods } from './pathfinder';
+export { QueryMethods } from './query';
+export { TrustMethods } from './trust';
+export { BalanceMethods } from './balance';
+export { AvatarMethods } from './avatar';
+export { ProfileMethods } from './profile';
+export { TokenMethods } from './token';
+export { InvitationMethods } from './invitation';
+export { TransactionMethods } from './transaction';
+export { GroupMethods } from './group';

package/dist/methods/invitation.d.ts

@@ -0,0 +1,61 @@
+import type { RpcClient } from '../client';
+import type { Address, AvatarInfo } from '@aboutcircles/sdk-types';
+/**
+ * Invitation RPC methods
+ */
+export declare class InvitationMethods {
+    private client;
+    constructor(client: RpcClient);
+    private transformQueryResponse;
+    /**
+     * Get the avatar that invited a specific avatar
+     *
+     * @param address - The address of the invited avatar
+     * @returns The address of the inviting avatar or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const inviter = await rpc.invitation.getInvitedBy('0xde374ece6fa50e781e81aac78e811b33d16912c7');
+     * console.log(inviter); // '0x...'
+     * ```
+     */
+    getInvitedBy(address: Address): Promise<Address | undefined>;
+    /**
+     * Get the list of avatars who have invited this avatar
+     * Checks v2 trust relations and validates that inviters have enough balance
+     *
+     * @param address - The address to check for invitations
+     * @returns Array of avatar info for valid inviters
+     *
+     * @example
+     * ```typescript
+     * const invitations = await rpc.invitation.getInvitations('0xde374ece6fa50e781e81aac78e811b33d16912c7');
+     * console.log(invitations); // Array of AvatarInfo
+     * ```
+     */
+    getInvitations(address: Address): Promise<AvatarInfo[]>;
+    /**
+     * Get the list of accounts that were invited by a specific avatar
+     *
+     * @param address - The address of the inviter
+     * @param accepted - If true, returns accepted invitations; if false, returns pending invitations
+     * @returns Array of invited addresses
+     *
+     * @example
+     * ```typescript
+     * // Get accepted invitations
+     * const accepted = await rpc.invitation.getInvitationsFrom(
+     *   '0xde374ece6fa50e781e81aac78e811b33d16912c7',
+     *   true
+     * );
+     *
+     * // Get pending invitations
+     * const pending = await rpc.invitation.getInvitationsFrom(
+     *   '0xde374ece6fa50e781e81aac78e811b33d16912c7',
+     *   false
+     * );
+     * ```
+     */
+    getInvitationsFrom(address: Address, accepted?: boolean): Promise<Address[]>;
+}
+//# sourceMappingURL=invitation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"invitation.d.ts","sourceRoot":"","sources":["../../src/methods/invitation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAsC,MAAM,yBAAyB,CAAC;AAOvG;;GAEG;AACH,qBAAa,iBAAiB;IAChB,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,SAAS;IAErC,OAAO,CAAC,sBAAsB;IAW9B;;;;;;;;;;;OAWG;IACG,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC;IAgClE;;;;;;;;;;;;OAYG;IACG,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAqF7D;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,kBAAkB,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,GAAE,OAAe,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;CAoF1F"}