@aboutcircles/sdk-rpc 0.1.0

package/dist/methods/query.js

@@ -0,0 +1,87 @@
+import { checksumAddresses } from '../utils';
+/**
+ * Query and table RPC methods
+ */
+export class QueryMethods {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Query tables with filters
+     *
+     * @param params - Query parameters including namespace, table, columns, filters, and ordering
+     * @returns Array of query results
+     *
+     * @example
+     * ```typescript
+     * const results = await rpc.query.query({
+     *   Namespace: 'V_CrcV2',
+     *   Table: 'TrustRelations',
+     *   Columns: [],
+     *   Filter: [{
+     *     Type: 'Conjunction',
+     *     ConjunctionType: 'Or',
+     *     Predicates: [
+     *       {
+     *         Type: 'FilterPredicate',
+     *         FilterType: 'Equals',
+     *         Column: 'truster',
+     *         Value: '0xae3a29a9ff24d0e936a5579bae5c4179c4dff565'
+     *       },
+     *       {
+     *         Type: 'FilterPredicate',
+     *         FilterType: 'Equals',
+     *         Column: 'trustee',
+     *         Value: '0xae3a29a9ff24d0e936a5579bae5c4179c4dff565'
+     *       }
+     *     ]
+     *   }],
+     *   Order: []
+     * });
+     * ```
+     */
+    async query(params) {
+        const result = await this.client.call('circles_query', [params]);
+        return checksumAddresses(result);
+    }
+    /**
+     * Return all available namespaces and tables which can be queried
+     *
+     * @returns Array of table information
+     *
+     * @example
+     * ```typescript
+     * const tables = await rpc.query.tables();
+     * console.log(tables);
+     * ```
+     */
+    async tables() {
+        return this.client.call('circles_tables', []);
+    }
+    /**
+     * Query events of specific types within a block range
+     *
+     * @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
+     *
+     * @example
+     * ```typescript
+     * const events = await rpc.query.events(
+     *   38000000,
+     *   null,
+     *   ['CrcV1_Trust'],
+     *   null,
+     *   false
+     * );
+     * ```
+     */
+    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);
+    }
+}

package/dist/methods/token.d.ts

@@ -0,0 +1,61 @@
+import type { RpcClient } from '../client';
+import type { Address, TokenInfo, TokenHolder, SortOrder } from '@aboutcircles/sdk-types';
+import { PagedQuery } from '../pagedQuery';
+/**
+ * Token information RPC methods
+ */
+export declare class TokenMethods {
+    private client;
+    constructor(client: RpcClient);
+    /**
+     * Get token information for a specific token address
+     *
+     * @param address - The token address to query
+     * @returns Token information or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const tokenInfo = await rpc.token.getTokenInfo('0x0d8c4901dd270fe101b8014a5dbecc4e4432eb1e');
+     * console.log(tokenInfo);
+     * ```
+     */
+    getTokenInfo(address: Address): Promise<TokenInfo | undefined>;
+    /**
+     * Get token information for multiple token addresses in batch
+     *
+     * @param addresses - Array of token addresses to query
+     * @returns Array of token information objects
+     *
+     * @example
+     * ```typescript
+     * const tokenInfos = await rpc.token.getTokenInfoBatch([
+     *   '0x0d8c4901dd270fe101b8014a5dbecc4e4432eb1e',
+     *   '0x86533d1ada8ffbe7b6f7244f9a1b707f7f3e239b'
+     * ]);
+     * ```
+     */
+    getTokenInfoBatch(addresses: Address[]): Promise<TokenInfo[]>;
+    /**
+     * Get token holders for a specific token address with pagination
+     *
+     * @param tokenAddress - The token address to query holders for
+     * @param limit - Maximum number of results per page (default: 100)
+     * @param sortOrder - Sort order for results (default: 'DESC' - highest balance first)
+     * @returns PagedQuery instance for token holders
+     *
+     * @example
+     * ```typescript
+     * const holdersQuery = rpc.token.getTokenHolders('0x42cedde51198d1773590311e2a340dc06b24cb37', 10);
+     *
+     * while (await holdersQuery.queryNextPage()) {
+     *   const page = holdersQuery.currentPage!;
+     *   console.log(`Found ${page.size} holders`);
+     *   page.results.forEach(holder => {
+     *     console.log(`${holder.account}: ${holder.demurragedTotalBalance}`);
+     *   });
+     * }
+     * ```
+     */
+    getTokenHolders(tokenAddress: Address, limit?: number, sortOrder?: SortOrder): PagedQuery<TokenHolder>;
+}
+//# sourceMappingURL=token.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../../src/methods/token.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAE1F,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C;;GAEG;AACH,qBAAa,YAAY;IACX,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,SAAS;IAErC;;;;;;;;;;;OAWG;IACG,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IAKpE;;;;;;;;;;;;;OAaG;IACG,iBAAiB,CAAC,SAAS,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAenE;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,eAAe,CACb,YAAY,EAAE,OAAO,EACrB,KAAK,GAAE,MAAY,EACnB,SAAS,GAAE,SAAkB,GAC5B,UAAU,CAAC,WAAW,CAAC;CAiC3B"}

package/dist/methods/token.js

@@ -0,0 +1,99 @@
+import { normalizeAddress, parseStringsToBigInt, checksumAddresses } from '../utils';
+import { PagedQuery } from '../pagedQuery';
+/**
+ * Token information RPC methods
+ */
+export class TokenMethods {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Get token information for a specific token address
+     *
+     * @param address - The token address to query
+     * @returns Token information or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const tokenInfo = await rpc.token.getTokenInfo('0x0d8c4901dd270fe101b8014a5dbecc4e4432eb1e');
+     * console.log(tokenInfo);
+     * ```
+     */
+    async getTokenInfo(address) {
+        const results = await this.getTokenInfoBatch([address]);
+        return results.length > 0 ? results[0] : undefined;
+    }
+    /**
+     * Get token information for multiple token addresses in batch
+     *
+     * @param addresses - Array of token addresses to query
+     * @returns Array of token information objects
+     *
+     * @example
+     * ```typescript
+     * const tokenInfos = await rpc.token.getTokenInfoBatch([
+     *   '0x0d8c4901dd270fe101b8014a5dbecc4e4432eb1e',
+     *   '0x86533d1ada8ffbe7b6f7244f9a1b707f7f3e239b'
+     * ]);
+     * ```
+     */
+    async getTokenInfoBatch(addresses) {
+        if (addresses.length === 0) {
+            return [];
+        }
+        const normalizedAddresses = addresses.map(addr => normalizeAddress(addr));
+        const result = await this.client.call('circles_getTokenInfoBatch', [normalizedAddresses]);
+        const parsed = result.map(item => parseStringsToBigInt(item));
+        return checksumAddresses(parsed);
+    }
+    /**
+     * Get token holders for a specific token address with pagination
+     *
+     * @param tokenAddress - The token address to query holders for
+     * @param limit - Maximum number of results per page (default: 100)
+     * @param sortOrder - Sort order for results (default: 'DESC' - highest balance first)
+     * @returns PagedQuery instance for token holders
+     *
+     * @example
+     * ```typescript
+     * const holdersQuery = rpc.token.getTokenHolders('0x42cedde51198d1773590311e2a340dc06b24cb37', 10);
+     *
+     * while (await holdersQuery.queryNextPage()) {
+     *   const page = holdersQuery.currentPage!;
+     *   console.log(`Found ${page.size} holders`);
+     *   page.results.forEach(holder => {
+     *     console.log(`${holder.account}: ${holder.demurragedTotalBalance}`);
+     *   });
+     * }
+     * ```
+     */
+    getTokenHolders(tokenAddress, limit = 100, sortOrder = 'DESC') {
+        const normalizedTokenAddress = normalizeAddress(tokenAddress);
+        return new PagedQuery(this.client, {
+            namespace: 'V_CrcV2',
+            table: 'BalancesByAccountAndToken',
+            columns: ['account', 'tokenAddress', 'demurragedTotalBalance'],
+            filter: [{
+                    Type: 'FilterPredicate',
+                    FilterType: 'Equals',
+                    Column: 'tokenAddress',
+                    Value: normalizedTokenAddress
+                }],
+            cursorColumns: [
+                { name: 'demurragedTotalBalance', sortOrder },
+                { name: 'account', sortOrder: 'ASC' } // Secondary sort for deterministic ordering
+            ],
+            orderColumns: [
+                { Column: 'demurragedTotalBalance', SortOrder: sortOrder },
+                { Column: 'account', SortOrder: 'ASC' }
+            ],
+            limit,
+            sortOrder
+        }, (row) => ({
+            account: row.account,
+            tokenAddress: row.tokenAddress,
+            demurragedTotalBalance: row.demurragedTotalBalance
+        }));
+    }
+}

package/dist/methods/transaction.d.ts

@@ -0,0 +1,41 @@
+import type { RpcClient } from '../client';
+import type { Address } from '@aboutcircles/sdk-types';
+import type { TransactionHistoryRow } from '../types';
+import { PagedQuery } from '../pagedQuery';
+/**
+ * Transaction history RPC methods
+ */
+export declare class TransactionMethods {
+    private client;
+    constructor(client: RpcClient);
+    /**
+     * Get transaction history for an address using cursor-based pagination
+     *
+     * Returns a PagedQuery instance that can be used to fetch transaction history page by page.
+     * Automatically calculates circle amounts for each v2 transaction.
+     *
+     * @param avatar - Avatar address to query transaction history for
+     * @param limit - Number of transactions per page (default: 50)
+     * @param sortOrder - Sort order for results (default: 'DESC')
+     * @returns PagedQuery instance for iterating through transaction history
+     *
+     * @example
+     * ```typescript
+     * const query = rpc.transaction.getTransactionHistory('0xAvatar...', 50);
+     *
+     * // Get first page
+     * await query.queryNextPage();
+     * query.currentPage.results.forEach(tx => {
+     *   console.log(`${tx.from} -> ${tx.to}: ${tx.circles} CRC`);
+     * });
+     *
+     * // Get next page if available
+     * if (query.currentPage.hasMore) {
+     *   await query.queryNextPage();
+     *   // Process next page...
+     * }
+     * ```
+     */
+    getTransactionHistory(avatar: Address, limit?: number, sortOrder?: 'ASC' | 'DESC'): PagedQuery<TransactionHistoryRow>;
+}
+//# sourceMappingURL=transaction.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../../src/methods/transaction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,KAAK,EAAE,OAAO,EAAU,MAAM,yBAAyB,CAAC;AAC/D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAGtD,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAiC3C;;GAEG;AACH,qBAAa,kBAAkB;IACjB,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,SAAS;IAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,qBAAqB,CACnB,MAAM,EAAE,OAAO,EACf,KAAK,GAAE,MAAW,EAClB,SAAS,GAAE,KAAK,GAAG,MAAe,GACjC,UAAU,CAAC,qBAAqB,CAAC;CAyDrC"}

package/dist/methods/transaction.js

@@ -0,0 +1,111 @@
+import { normalizeAddress, checksumAddresses } from '../utils';
+import { CirclesConverter } from '@aboutcircles/sdk-utils';
+import { PagedQuery } from '../pagedQuery';
+/**
+ * Calculate circle amounts for v2 transactions
+ */
+function calculateCircleAmounts(value, timestamp) {
+    // v2: value is attoCircles (demurraged)
+    const attoCircles = BigInt(value);
+    const circles = CirclesConverter.attoCirclesToCircles(attoCircles);
+    const attoCrc = CirclesConverter.attoCirclesToAttoCrc(attoCircles, BigInt(timestamp));
+    const crc = CirclesConverter.attoCirclesToCircles(attoCrc);
+    const staticAttoCircles = CirclesConverter.attoCirclesToAttoStaticCircles(attoCircles, BigInt(timestamp));
+    const staticCircles = CirclesConverter.attoCirclesToCircles(staticAttoCircles);
+    return {
+        attoCircles,
+        circles,
+        staticAttoCircles,
+        staticCircles,
+        attoCrc,
+        crc,
+    };
+}
+/**
+ * Transaction history RPC methods
+ */
+export class TransactionMethods {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Get transaction history for an address using cursor-based pagination
+     *
+     * Returns a PagedQuery instance that can be used to fetch transaction history page by page.
+     * Automatically calculates circle amounts for each v2 transaction.
+     *
+     * @param avatar - Avatar address to query transaction history for
+     * @param limit - Number of transactions per page (default: 50)
+     * @param sortOrder - Sort order for results (default: 'DESC')
+     * @returns PagedQuery instance for iterating through transaction history
+     *
+     * @example
+     * ```typescript
+     * const query = rpc.transaction.getTransactionHistory('0xAvatar...', 50);
+     *
+     * // Get first page
+     * await query.queryNextPage();
+     * query.currentPage.results.forEach(tx => {
+     *   console.log(`${tx.from} -> ${tx.to}: ${tx.circles} CRC`);
+     * });
+     *
+     * // Get next page if available
+     * if (query.currentPage.hasMore) {
+     *   await query.queryNextPage();
+     *   // Process next page...
+     * }
+     * ```
+     */
+    getTransactionHistory(avatar, limit = 50, sortOrder = 'DESC') {
+        const normalized = normalizeAddress(avatar);
+        const filter = [
+            {
+                Type: 'Conjunction',
+                ConjunctionType: 'And',
+                Predicates: [
+                    {
+                        Type: 'FilterPredicate',
+                        FilterType: 'Equals',
+                        Column: 'version',
+                        Value: 2,
+                    },
+                    {
+                        Type: 'Conjunction',
+                        ConjunctionType: 'Or',
+                        Predicates: [
+                            {
+                                Type: 'FilterPredicate',
+                                FilterType: 'Equals',
+                                Column: 'from',
+                                Value: normalized,
+                            },
+                            {
+                                Type: 'FilterPredicate',
+                                FilterType: 'Equals',
+                                Column: 'to',
+                                Value: normalized,
+                            },
+                        ],
+                    },
+                ],
+            },
+        ];
+        return new PagedQuery(this.client, {
+            namespace: 'V_Crc',
+            table: 'TransferSummary',
+            sortOrder,
+            columns: [], // Empty array returns all columns
+            filter,
+            limit,
+        }, (row) => {
+            // Calculate circle amounts
+            const amounts = calculateCircleAmounts(row.value, row.timestamp);
+            const result = {
+                ...row,
+                ...amounts,
+            };
+            return checksumAddresses(result);
+        });
+    }
+}

package/dist/methods/trust.d.ts

@@ -0,0 +1,114 @@
+import type { RpcClient } from '../client';
+import type { Address, TrustRelation, AggregatedTrustRelation } from '@aboutcircles/sdk-types';
+import { PagedQuery } from '../pagedQuery';
+/**
+ * Trust relation RPC methods
+ */
+export declare class TrustMethods {
+    private client;
+    constructor(client: RpcClient);
+    private transformQueryResponse;
+    /**
+     * Query the common trust relations of two addresses
+     * (only common outgoing trust relations are considered)
+     *
+     * @param address1 - First address
+     * @param address2 - Second address
+     * @returns Array of common trusted addresses
+     *
+     * @example
+     * ```typescript
+     * const commonTrust = await rpc.trust.getCommonTrust(
+     *   '0xde374ece6fa50e781e81aac78e811b33d16912c7',
+     *   '0xe8fc7a2d0573e5164597b05f14fa9a7fca7b215c'
+     * );
+     * ```
+     */
+    getCommonTrust(address1: Address, address2: Address): Promise<Address[]>;
+    /**
+     * Get trust relations for an address using cursor-based pagination
+     *
+     * Returns a PagedQuery instance for iterating through all v2 trust relations for the given avatar.
+     *
+     * @param avatar - Avatar address to query trust relations for
+     * @param limit - Number of trust relations per page (default: 100)
+     * @param sortOrder - Sort order for results (default: 'DESC')
+     * @returns PagedQuery instance for iterating through trust relations
+     *
+     * @example
+     * ```typescript
+     * const query = rpc.trust.getTrustRelations('0xAvatar...', 100);
+     *
+     * // Get first page
+     * await query.queryNextPage();
+     * query.currentPage.results.forEach(relation => {
+     *   console.log(`${relation.truster} trusts ${relation.trustee}`);
+     * });
+     * ```
+     */
+    getTrustRelations(avatar: Address, limit?: number, sortOrder?: 'ASC' | 'DESC'): PagedQuery<TrustRelation>;
+    /**
+     * Get aggregated trust relations for an address
+     * Groups trust relations by counterpart and determines relationship type
+     *
+     * Note: This method fetches ALL trust relations for aggregation.
+     *
+     * @param avatar - Avatar address to query trust relations for
+     * @returns Aggregated trust relations with relationship types
+     *
+     * @example
+     * ```typescript
+     * const aggregated = await rpc.trust.getAggregatedTrustRelations(
+     *   '0xde374ece6fa50e781e81aac78e811b33d16912c7'
+     * );
+     * // Returns: [
+     * //   { subjectAvatar: '0x...', relation: 'mutuallyTrusts', objectAvatar: '0x...', timestamp: 123 },
+     * //   { subjectAvatar: '0x...', relation: 'trusts', objectAvatar: '0x...', timestamp: 456 }
+     * // ]
+     * ```
+     */
+    getAggregatedTrustRelations(avatar: Address): Promise<AggregatedTrustRelation[]>;
+    /**
+     * Get addresses that trust the given avatar (incoming trust)
+     *
+     * @param avatar - Avatar address to query
+     * @returns Array of trust relations where others trust this avatar
+     *
+     * @example
+     * ```typescript
+     * const trustedBy = await rpc.trust.getTrustedBy(
+     *   '0xde374ece6fa50e781e81aac78e811b33d16912c7'
+     * );
+     * ```
+     */
+    getTrustedBy(avatar: Address): Promise<AggregatedTrustRelation[]>;
+    /**
+     * Get addresses that the given avatar trusts (outgoing trust)
+     *
+     * @param avatar - Avatar address to query
+     * @returns Array of trust relations where this avatar trusts others
+     *
+     * @example
+     * ```typescript
+     * const trusts = await rpc.trust.getTrusts(
+     *   '0xde374ece6fa50e781e81aac78e811b33d16912c7'
+     * );
+     * ```
+     */
+    getTrusts(avatar: Address): Promise<AggregatedTrustRelation[]>;
+    /**
+     * Get mutual trust relations for the given avatar
+     *
+     * @param avatar - Avatar address to query
+     * @returns Array of trust relations where both parties trust each other
+     *
+     * @example
+     * ```typescript
+     * const mutualTrusts = await rpc.trust.getMutualTrusts(
+     *   '0xde374ece6fa50e781e81aac78e811b33d16912c7'
+     * );
+     * ```
+     */
+    getMutualTrusts(avatar: Address): Promise<AggregatedTrustRelation[]>;
+}
+//# sourceMappingURL=trust.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"trust.d.ts","sourceRoot":"","sources":["../../src/methods/trust.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAmD,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAEhJ,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C;;GAEG;AACH,qBAAa,YAAY;IACX,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,SAAS;IAErC,OAAO,CAAC,sBAAsB;IAW9B;;;;;;;;;;;;;;;OAeG;IAEG,cAAc,CAAC,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAQ9E;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,iBAAiB,CACf,MAAM,EAAE,OAAO,EACf,KAAK,GAAE,MAAY,EACnB,SAAS,GAAE,KAAK,GAAG,MAAe,GACjC,UAAU,CAAC,aAAa,CAAC;IA4D5B;;;;;;;;;;;;;;;;;;;OAmBG;IACG,2BAA2B,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,uBAAuB,EAAE,CAAC;IAuDtF;;;;;;;;;;;;OAYG;IACG,YAAY,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,uBAAuB,EAAE,CAAC;IAOvE;;;;;;;;;;;;OAYG;IACG,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,uBAAuB,EAAE,CAAC;IAOpE;;;;;;;;;;;;OAYG;IACG,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,uBAAuB,EAAE,CAAC;CAM3E"}