@aboutcircles/sdk 0.1.0

package/dist/avatars/HumanAvatar.d.ts

@@ -0,0 +1,412 @@
+import type { Address, AvatarRow, ContractRunner, TokenBalanceRow, GroupMembershipRow, GroupRow } from '@aboutcircles/sdk-types';
+import type { TransactionReceipt } from 'viem';
+import type { Core } from '@aboutcircles/sdk-core';
+import { CommonAvatar, type PathfindingOptions } from './CommonAvatar';
+/**
+ * HumanAvatar class implementation
+ * Provides a simplified, user-friendly wrapper around Circles protocol for human avatars
+ *
+ * This class represents a human avatar in the Circles ecosystem and provides
+ * methods for managing trust relationships, personal token minting, transfers, and more.
+ */
+export declare class HumanAvatar extends CommonAvatar {
+    constructor(address: Address, core: Core, contractRunner?: ContractRunner, avatarInfo?: AvatarRow);
+    readonly balances: {
+        getTotal: () => Promise<bigint>;
+        getTokenBalances: () => Promise<TokenBalanceRow[]>;
+        getTotalSupply: () => Promise<bigint>;
+        /**
+         * Get the maximum amount that can be replenished (converted to unwrapped personal CRC)
+         * This calculates how much of your wrapped tokens and other tokens can be converted
+         * into your own unwrapped ERC1155 personal CRC tokens using pathfinding
+         *
+         * @param options Optional pathfinding options
+         * @returns Maximum replenishable amount in atto-circles
+         *
+         * @example
+         * ```typescript
+         * const maxReplenishable = await avatar.balances.getMaxReplenishable();
+         * console.log('Can replenish:', CirclesConverter.attoCirclesToCircles(maxReplenishable), 'CRC');
+         * ```
+         */
+        getMaxReplenishable: (options?: PathfindingOptions) => Promise<bigint>;
+        /**
+         * Replenish unwrapped personal CRC tokens by converting wrapped/other tokens
+         *
+         * This method uses pathfinding to find the best way to convert your available tokens
+         * (including wrapped tokens) into unwrapped ERC1155 personal CRC tokens.
+         *
+         * Useful when you have wrapped tokens or other people's tokens and want to
+         * convert them to your own personal unwrapped tokens for transfers.
+         *
+         * @param options Optional pathfinding options
+         * @returns Transaction receipt
+         *
+         * @example
+         * ```typescript
+         * // Convert all available wrapped/other tokens to unwrapped personal CRC
+         * const receipt = await avatar.balances.replenish();
+         * console.log('Replenished personal tokens, tx hash:', receipt.hash);
+         * ```
+         */
+        replenish: (options?: PathfindingOptions) => Promise<TransactionReceipt>;
+    };
+    readonly invite: {
+        /**
+         * Invite someone to Circles by escrowing 100 CRC tokens
+         *
+         * This batches two transactions atomically:
+         * 1. Establishes trust with the invitee (with indefinite expiry)
+         * 2. Transfers 100 of your personal CRC tokens to the InvitationEscrow contract
+         *
+         * The tokens are held in escrow until the invitee redeems the invitation by registering.
+         *
+         * Requirements:
+         * - You must have at least 100 CRC available
+         * - Invitee must not be already registered in Circles
+         * - You can only have one active invitation per invitee
+         *
+         * @param invitee The address to invite
+         * @returns Transaction response
+         *
+         * @example
+         * ```typescript
+         * // Invite someone with 100 CRC (automatically establishes trust)
+         * await avatar.invite.send('0x123...');
+         * ```
+         */
+        send: (invitee: Address) => Promise<TransactionReceipt>;
+        /**
+         * Revoke a previously sent invitation
+         *
+         * This returns the escrowed tokens (with demurrage applied) back to you
+         * as wrapped ERC20 tokens.
+         *
+         * @param invitee The address whose invitation to revoke
+         * @returns Transaction response
+         *
+         * @example
+         * ```typescript
+         * await avatar.invite.revoke('0x123...');
+         * ```
+         */
+        revoke: (invitee: Address) => Promise<TransactionReceipt>;
+        /**
+         * Revoke all active invitations at once
+         *
+         * This returns all escrowed tokens (with demurrage applied) back to you
+         * as wrapped ERC20 tokens in a single transaction.
+         *
+         * @returns Transaction response
+         *
+         * @example
+         * ```typescript
+         * await avatar.invite.revokeAll();
+         * ```
+         */
+        revokeAll: () => Promise<TransactionReceipt>;
+        /**
+         * Redeem an invitation received from an inviter
+         *
+         * This claims the escrowed tokens from a specific inviter and refunds
+         * all other inviters' escrows back to them.
+         *
+         * @param inviter The address of the inviter whose invitation to redeem
+         * @returns Transaction response
+         *
+         * @example
+         * ```typescript
+         * // Get all inviters first
+         * const inviters = await avatar.invite.getInviters();
+         *
+         * // Redeem invitation from the first inviter
+         * await avatar.invite.redeem(inviters[0]);
+         * ```
+         */
+        redeem: (inviter: Address) => Promise<TransactionReceipt>;
+        /**
+         * Get all addresses that have sent invitations to you
+         *
+         * @returns Array of inviter addresses
+         *
+         * @example
+         * ```typescript
+         * const inviters = await avatar.invite.getInviters();
+         * console.log(`You have ${inviters.length} pending invitations`);
+         * ```
+         */
+        getInviters: () => Promise<Address[]>;
+        /**
+         * Get all addresses you have invited
+         *
+         * @returns Array of invitee addresses
+         *
+         * @example
+         * ```typescript
+         * const invitees = await avatar.invite.getInvitees();
+         * console.log(`You have invited ${invitees.length} people`);
+         * ```
+         */
+        getInvitees: () => Promise<Address[]>;
+        /**
+         * Get the escrowed amount and days since escrow for a specific invitation
+         *
+         * The amount returned has demurrage applied, so it decreases over time.
+         *
+         * @param inviter The inviter address (when checking invitations you received)
+         * @param invitee The invitee address (when checking invitations you sent)
+         * @returns Object with escrowedAmount (in atto-circles) and days since escrow
+         *
+         * @example
+         * ```typescript
+         * // Check an invitation you sent
+         * const { escrowedAmount, days_ } = await avatar.invite.getEscrowedAmount(
+         *   avatar.address,
+         *   '0xinvitee...'
+         * );
+         * console.log(`Escrowed: ${CirclesConverter.attoCirclesToCircles(escrowedAmount)} CRC`);
+         * console.log(`Days since escrow: ${days_}`);
+         *
+         * // Check an invitation you received
+         * const { escrowedAmount, days_ } = await avatar.invite.getEscrowedAmount(
+         *   '0xinviter...',
+         *   avatar.address
+         * );
+         * ```
+         */
+        getEscrowedAmount: (inviter: Address, invitee: Address) => Promise<import("@aboutcircles/sdk-types").EscrowedAmountAndDays>;
+    };
+    readonly personalToken: {
+        /**
+         * Get the available amount of personal tokens that can be minted
+         *
+         * This method calls the HubV2 contract's calculateIssuance function which returns:
+         * - Total issuance amount: The total amount of tokens that can be minted
+         * - Start period: The period when minting started
+         * - End period: The current period
+         *
+         * @returns Object containing issuance amount (in atto-circles), start period, and end period
+         *
+         * @example
+         * ```typescript
+         * const { amount, startPeriod, endPeriod } = await avatar.personalToken.getMintableAmount();
+         * console.log('Mintable amount:', CirclesConverter.attoCirclesToCircles(amount), 'CRC');
+         * console.log('Start period:', startPeriod.toString());
+         * console.log('End period:', endPeriod.toString());
+         * ```
+         */
+        getMintableAmount: () => Promise<{
+            amount: bigint;
+            startPeriod: bigint;
+            endPeriod: bigint;
+        }>;
+        /**
+         * Mint personal Circles tokens
+         * This claims all available personal tokens that have accrued since last mint
+         *
+         * @returns Transaction response
+         *
+         * @example
+         * ```typescript
+         * const receipt = await avatar.personalToken.mint();
+         * console.log('Minted tokens, tx hash:', receipt.hash);
+         * ```
+         */
+        mint: () => Promise<TransactionReceipt>;
+        /**
+         * Stop personal token minting
+         * This permanently stops the ability to mint new personal tokens
+         *
+         * WARNING: This action is irreversible!
+         *
+         * @returns Transaction response
+         *
+         * @example
+         * ```typescript
+         * const receipt = await avatar.personalToken.stop();
+         * console.log('Stopped minting, tx hash:', receipt.hash);
+         * ```
+         */
+        stop: () => Promise<TransactionReceipt>;
+    };
+    readonly groupToken: {
+        /**
+         * Mint group tokens by transferring collateral to the group's mint handler
+         * Uses pathfinding to transfer tokens along the trust network, including wrapped tokens
+         *
+         * @param group The group address to mint tokens from
+         * @param amount Amount of tokens to transfer to the mint handler (in atto-circles)
+         * @returns Transaction receipt
+         *
+         * @example
+         * ```typescript
+         * // Mint group tokens by sending 100 CRC to the group's mint handler
+         * const receipt = await avatar.groupToken.mint('0xGroupAddress...', BigInt(100e18));
+         * ```
+         */
+        mint: (group: Address, amount: bigint) => Promise<TransactionReceipt>;
+        /**
+         * Get the maximum amount that can be minted for a group
+         * This calculates the maximum transferable amount to the group's mint handler
+         * including wrapped token balances
+         *
+         * @param group The group address
+         * @returns Maximum mintable amount in atto-circles
+         *
+         * @example
+         * ```typescript
+         * const maxMintable = await avatar.groupToken.getMaxMintableAmount('0xGroupAddress...');
+         * console.log('Can mint up to:', maxMintable.toString(), 'atto-circles');
+         * ```
+         */
+        getMaxMintableAmount: (group: Address) => Promise<bigint>;
+        /**
+         * Automatically redeem collateral tokens from a Base Group's treasury
+         *
+         * Performs automatic redemption by determining trusted collaterals and using pathfinder for optimal flow.
+         * Only supports Base Group types. The function uses pathfinder to determine the optimal redemption path
+         * and validates that sufficient liquidity exists before attempting redemption.
+         *
+         * @param group The address of the Base Group from which to redeem collateral tokens
+         * @param amount The amount of group tokens to redeem for collateral (must be > 0 and <= max redeemable)
+         * @returns A Promise resolving to the transaction receipt upon successful automatic redemption
+         *
+         * @example
+         * ```typescript
+         * // Redeem 100 group tokens for collateral
+         * const receipt = await avatar.groupToken.redeem('0xGroupAddress...', BigInt(100e18));
+         * ```
+         */
+        redeem: (group: Address, amount: bigint) => Promise<TransactionReceipt>;
+        properties: {
+            /**
+             * Get the owner of a specific group
+             * @param group The group address
+             * @returns The owner address of the group
+             */
+            owner: (group: Address) => Promise<Address>;
+            /**
+             * Get the mint handler address of a specific group
+             * @param group The group address
+             * @returns The mint handler address
+             */
+            mintHandler: (group: Address) => Promise<Address>;
+            /**
+             * Get the treasury (redemption handler) address of a specific group
+             * @param group The group address
+             * @returns The treasury address where redemptions are handled
+             */
+            treasury: (group: Address) => Promise<Address>;
+            /**
+             * Get the service address of a specific group
+             * @param group The group address
+             * @returns The service address
+             */
+            service: (group: Address) => Promise<Address>;
+            /**
+             * Get the fee collection address of a specific group
+             * @param group The group address
+             * @returns The fee collection address
+             */
+            feeCollection: (group: Address) => Promise<Address>;
+            /**
+             * Get all membership conditions for a specific group
+             * @param group The group address
+             * @returns Array of membership condition addresses
+             */
+            getMembershipConditions: (group: Address) => Promise<Address[]>;
+        };
+    };
+    readonly group: {
+        properties: {
+            /**
+             * Get the owner of a specific group
+             * @param group The group address
+             * @returns The owner address of the group
+             */
+            owner: (group: Address) => Promise<Address>;
+            /**
+             * Get the mint handler address of a specific group
+             * @param group The group address
+             * @returns The mint handler address
+             */
+            mintHandler: (group: Address) => Promise<Address>;
+            /**
+             * Get the treasury (redemption handler) address of a specific group
+             * @param group The group address
+             * @returns The treasury address where redemptions are handled
+             */
+            treasury: (group: Address) => Promise<Address>;
+            /**
+             * Get the service address of a specific group
+             * @param group The group address
+             * @returns The service address
+             */
+            service: (group: Address) => Promise<Address>;
+            /**
+             * Get the fee collection address of a specific group
+             * @param group The group address
+             * @returns The fee collection address
+             */
+            feeCollection: (group: Address) => Promise<Address>;
+            /**
+             * Get all membership conditions for a specific group
+             * @param group The group address
+             * @returns Array of membership condition addresses
+             */
+            getMembershipConditions: (group: Address) => Promise<Address[]>;
+        };
+        /**
+         * Get group memberships for this avatar using cursor-based pagination
+         *
+         * Returns a PagedQuery instance for iterating through all groups that this avatar is a member of,
+         * including membership details such as expiry time and when the membership was created.
+         *
+         * @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 = avatar.group.getGroupMemberships();
+         *
+         * // Get first page
+         * await query.queryNextPage();
+         * console.log(`Member of ${query.currentPage.size} groups (page 1)`);
+         *
+         * // Iterate through all memberships
+         * while (await query.queryNextPage()) {
+         *   query.currentPage.results.forEach(membership => {
+         *     console.log(`Group: ${membership.group}`);
+         *     console.log(`Expiry: ${new Date(membership.expiryTime * 1000).toLocaleDateString()}`);
+         *   });
+         * }
+         * ```
+         */
+        getGroupMemberships: (limit?: number, sortOrder?: "ASC" | "DESC") => import("@aboutcircles/sdk-rpc").PagedQuery<GroupMembershipRow>;
+        /**
+         * Get detailed information about all groups this avatar is a member of
+         *
+         * This method fetches group memberships and enriches them with full group details including
+         * name, symbol, owner, treasury, mint handler, member count, and other properties.
+         *
+         * @param limit Maximum number of memberships to return (default: 50)
+         * @returns Array of group detail rows
+         *
+         * @example
+         * ```typescript
+         * // Get detailed information about all group memberships
+         * const groups = await avatar.group.getGroupMembershipsWithDetails();
+         *
+         * groups.forEach(group => {
+         *   console.log(`Group: ${group.name} (${group.symbol})`);
+         *   console.log(`Owner: ${group.owner}`);
+         *   console.log(`Member count: ${group.memberCount}`);
+         *   console.log(`Treasury: ${group.treasury}`);
+         * });
+         * ```
+         */
+        getGroupMembershipsWithDetails: (limit?: number) => Promise<GroupRow[]>;
+    };
+}
+//# sourceMappingURL=HumanAvatar.d.ts.map

package/dist/avatars/HumanAvatar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HumanAvatar.d.ts","sourceRoot":"","sources":["../../src/avatars/HumanAvatar.ts"],"names":[],"mappings":"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"}