@aboutcircles/sdk 0.1.10 → 0.1.12

package/dist/avatars/HumanAvatar.js

@@ -1,10 +1,8 @@
 import { ValidationError } from '@aboutcircles/sdk-utils';
 import { SdkError } from '../errors';
 import { BaseGroupContract } from '@aboutcircles/sdk-core';
-import { encodeAbiParameters, parseAbiParameters, encodeFunctionData } from 'viem';
-import { referralsModuleAbi } from '@aboutcircles/sdk-abis';
-import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts';
 import { CommonAvatar } from './CommonAvatar';
+import { Invitations, InviteFarm } from '@aboutcircles/sdk-invitations';
 /**
  * HumanAvatar class implementation
  * Provides a simplified, user-friendly wrapper around Circles protocol for human avatars
@@ -96,252 +94,81 @@ export class HumanAvatar extends CommonAvatar {
     // ============================================================================
     // Trust methods are inherited from CommonAvatar
     // ============================================================================
-    // Invitation methods
-    invite = {
+    // ============================================================================
+    // Invitation methods using the Invitations module
+    // ============================================================================
+    _invitations = new Invitations(this.core.config);
+    _inviteFarm = new InviteFarm(this.core.config);
+    invitation = {
         /**
-         * 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...');
-         * ```
+         * Get a referral code for inviting a new user who doesn't have a Safe wallet yet.
+         * Generates private key, finds proxy inviters, builds tx batch, saves referral data.
+         * @returns Transactions to execute and the private key to share with invitee
          */
-        send: async (invitee) => {
-            //@todo add replenish/unwrap logic
-            // Create trust transaction (indefinite trust)
-            const trustTx = this.core.hubV2.trust(invitee, BigInt('0xFFFFFFFFFFFFFFFFFFFFFFFF'));
-            // Get the token ID for this avatar's personal token
-            const tokenId = await this.core.hubV2.toTokenId(this.address);
-            // ABI-encode the invitee address as 32 bytes
-            const encodedInvitee = encodeAbiParameters(parseAbiParameters('address'), [invitee]);
-            // Create the safeTransferFrom transaction to the InvitationEscrow contract
-            const transferTx = this.core.hubV2.safeTransferFrom(this.address, this.core.config.invitationEscrowAddress, tokenId, BigInt(100e18), encodedInvitee);
-            // Batch both transactions: trust + invitation transfer
-            return await this.runner.sendTransaction([trustTx, transferTx]);
+        getReferralCode: async () => {
+            return this._invitations.generateReferral(this.address);
         },
         /**
-         * 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...');
-         * ```
+         * Invite a user who already has a Safe wallet but is not yet registered in Circles.
+         * @param invitee Address of the invitee (must have existing Safe, NOT registered in Circles)
          */
-        revoke: async (invitee) => {
-            const revokeTx = this.core.invitationEscrow.revokeInvitation(invitee);
-            return await this.runner.sendTransaction([revokeTx]);
+        invite: async (invitee) => {
+            return this._invitations.generateInvite(this.address, invitee);
         },
         /**
-         * 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();
-         * ```
+         * Get proxy inviters who can facilitate invitations.
+         * These are addresses that trust this avatar, are trusted by the invitation module,
+         * and have sufficient balance (96 CRC per invite).
          */
-        revokeAll: async () => {
-            const revokeAllTx = this.core.invitationEscrow.revokeAllInvitations();
-            return await this.runner.sendTransaction([revokeAllTx]);
+        getProxyInviters: async () => {
+            return this._invitations.getRealInviters(this.address);
         },
         /**
-         * 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]);
-         * ```
+         * Find a path from this avatar to the invitation module.
+         * @param proxyInviterAddress Optional specific proxy inviter to route through
          */
-        // @todo check if it functionable
-        redeem: async (inviter) => {
-            const redeemTx = this.core.invitationEscrow.redeemInvitation(inviter);
-            return await this.runner.sendTransaction([redeemTx]);
+        findInvitePath: async (proxyInviterAddress) => {
+            return this._invitations.findInvitePath(this.address, proxyInviterAddress);
         },
         /**
-         * 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`);
-         * ```
+         * Compute the deterministic Safe address for a given signer using CREATE2.
+         * @param signer The signer public address
          */
-        getInviters: async () => {
-            return await this.core.invitationEscrow.getInviters(this.address);
+        computeAddress: (signer) => {
+            return this._invitations.computeAddress(signer);
         },
         /**
-         * 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`);
-         * ```
+         * Generate batch invitations using the InvitationFarm.
+         * @param count Number of invitations to generate
          */
-        getInvitees: async () => {
-            return await this.core.invitationEscrow.getInvitees(this.address);
+        generateInvites: async (count) => {
+            const result = await this._inviteFarm.generateInvites(this.address, count);
+            const receipt = await this.runner.sendTransaction(result.transactions);
+            return {
+                secrets: result.invites.map((inv) => inv.secret),
+                signers: result.invites.map((inv) => inv.signer),
+                transactionReceipt: receipt,
+            };
         },
-        /**
-         * 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: async (inviter, invitee) => {
-            return await this.core.invitationEscrow.getEscrowedAmountAndDays(inviter, invitee);
+        /** Get the remaining invite quota for this avatar */
+        getQuota: async () => {
+            return this._inviteFarm.getQuota(this.address);
+        },
+        /** Get the invitation fee (96 CRC) */
+        getInvitationFee: async () => {
+            return this._inviteFarm.getInvitationFee();
+        },
+        /** Get the invitation module address from the farm */
+        getInvitationModule: async () => {
+            return this._inviteFarm.getInvitationModule();
         },
         /**
-         * Generate new invitations and return associated secrets and signer addresses
-         *
-         * This function:
-         * 1. Calls invitationFarm.claimInvites() to get invitation IDs via eth_call
-         * 2. Generates random secrets for each invitation
-         * 3. Derives signer addresses from the secrets using ECDSA
-         * 4. Batches the claimInvites write call with safeBatchTransferFrom to transfer
-         *    invitation tokens (96 CRC each) to the invitation module
-         * 5. Returns the list of secrets and corresponding signers
-         *
-         * The data field in the batch transfer contains the count of generated secrets,
-         * which the contract uses to validate the transfer.
-         *
-         * @param numberOfInvites The number of invitations to generate
-         * @returns Promise containing arrays of secrets and signers for each generated invitation
-         *
-         * @throws {SdkError} If the transaction fails or invitations cannot be claimed
-         *
-         * @example
-         * ```typescript
-         * // Generate 5 invitations
-         * const result = await avatar.invite.generateInvites(5n);
-         *
-         * console.log('Generated invitations:');
-         * result.secrets.forEach((secret, index) => {
-         *   console.log(`Invitation ${index + 1}:`);
-         *   console.log(`  Secret: ${secret}`);
-         *   console.log(`  Signer: ${result.signers[index]}`);
-         * });
-         * ```
+         * List referrals for this avatar with key previews.
+         * @param limit Max referrals to return (default 10)
+         * @param offset Pagination offset (default 0)
          */
-        generateInvites: async (numberOfInvites) => {
-            if (numberOfInvites <= 0n) {
-                throw SdkError.operationFailed('generateInvites', 'numberOfInvites must be greater than 0');
-            }
-            // Step 1: Call eth_call to claimInvites to get invitation IDs (read-only simulation)
-            // This simulates the claimInvites call without actually modifying state
-            // to get the IDs that would be returned
-            const ids = (await this.core.invitationFarm.read('claimInvites', [numberOfInvites], {
-                from: this.address
-            }));
-            console.log("ids", ids);
-            if (!ids || ids.length === 0) {
-                throw SdkError.operationFailed('generateInvites', 'No invitation IDs returned from claimInvites');
-            }
-            // Step 2: Generate random secrets and derive signers
-            const secrets = [];
-            const signers = [];
-            for (let i = 0; i < numberOfInvites; i++) {
-                // Generate a random private key
-                const privateKey = generatePrivateKey();
-                secrets.push(privateKey);
-                // Derive the signer address from the private key
-                const account = privateKeyToAccount(privateKey);
-                signers.push(account.address.toLowerCase());
-            }
-            // Step 3: Get invitation module address
-            const invitationModuleAddress = await this.core.invitationFarm.invitationModule();
-            // Step 4: Referrals module address
-            const referralsModuleAddress = this.core.config.referralsModuleAddress;
-            // Step 5: Build the batch transaction
-            // - claimInvites write call (to actually claim the invites)
-            // - safeBatchTransferFrom to transfer invitation tokens to the invitation module
-            // Create the claimInvites write transaction
-            const claimInvitesWriteTx = this.core.invitationFarm.claimInvites(numberOfInvites);
-            // Step 6: Encode the createAccounts function call to the referrals module
-            // This call will be executed by the invitation module via the generic call proxy
-            const createAccountsCallData = encodeFunctionData({
-                abi: referralsModuleAbi,
-                functionName: 'createAccounts',
-                args: [signers],
-            });
-            // Step 7: Create safeBatchTransferFrom transaction to transfer invitation tokens to the invitation module
-            // - from: this avatar
-            // - to: invitation module
-            // - ids: the invitation IDs returned from claimInvites
-            // - amounts: all 96 CRC (96 * 10^18) per invitation
-            // - data: encoded as (address referralsModule, bytes callData) for the invitation module to execute
-            const amounts = [];
-            for (let i = 0; i < ids.length; i++) {
-                amounts.push(BigInt(96e18)); // 96 CRC in atto-circles
-            }
-            // Encode the data as (address, bytes) - referrals module address + createAccounts call data
-            const encodedData = encodeAbiParameters(parseAbiParameters('address, bytes'), [referralsModuleAddress, createAccountsCallData]);
-            const batchTransferTx = this.core.hubV2.safeBatchTransferFrom(this.address, invitationModuleAddress, ids, amounts, encodedData);
-            // Step 7: Execute the batch transaction
-            const receipt = await this.runner.sendTransaction([claimInvitesWriteTx, batchTransferTx]);
-            return {
-                secrets,
-                signers,
-                transactionReceipt: receipt,
-            };
+        listReferrals: async (limit = 10, offset = 0) => {
+            return this._inviteFarm.listReferrals(this.address, limit, offset);
         },
     };
     // Personal token / Minting methods