@aboutcircles/sdk-invitations 0.1.10 → 0.1.11

package/dist/Invitations.d.ts

@@ -1,4 +1,5 @@
 import type { Address, TransactionRequest, CirclesConfig } from '@aboutcircles/sdk-types';
+import type { ReferralPreviewList } from './types';
 export interface ProxyInviter {
     address: Address;
     possibleInvites: number;
@@ -24,7 +25,16 @@ export declare class Invitations {
      * @description
      * Sends a POST request to the referrals service to store referral data.
      */
-    private saveReferralData;
+    saveReferralData(inviter: Address, privateKey: `0x${string}`): Promise<void>;
+    /**
+     * List referrals for a given inviter with key previews
+     *
+     * @param inviter - Address of the inviter
+     * @param limit - Maximum number of referrals to return (default 10)
+     * @param offset - Number of referrals to skip for pagination (default 0)
+     * @returns Paginated list of referral previews with masked keys
+     */
+    listReferrals(inviter: Address, limit?: number, offset?: number): Promise<ReferralPreviewList>;
     /**
      * Order real inviters by preference (best to worst)
      *

package/dist/Invitations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Invitations.d.ts","sourceRoot":"","sources":["../src/Invitations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAmB1F,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,UAAU,CAAoB;IACtC,OAAO,CAAC,KAAK,CAAe;IAC5B,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,eAAe,CAAiC;gBAE5C,MAAM,EAAE,aAAa;IAsBjC;;;;;;;;OAQG;YACW,gBAAgB;IAmC9B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,iBAAiB;IAezB;;;;;;;;;;;;;;;;;OAiBG;IACG,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IA+CvF;;;;;;;;;;;OAWG;IACG,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,mBAAmB,CAAC,EAAE,OAAO;IA+CpE;;;;;;;;;;;;;;;;;OAiBG;IACG,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAwFhE;;;;;;;;;;;;;;OAcG;IACG,gBAAgB,CACpB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC;QAAE,YAAY,EAAE,kBAAkB,EAAE,CAAC;QAAC,UAAU,EAAE,KAAK,MAAM,EAAE,CAAA;KAAE,CAAC;IAiD7E;;;;;;;;;;;;;OAaG;IACG,kBAAkB,CAAC,SAAS,EAAE,OAAO,EAAE,EAAE,eAAe,GAAE,OAAc,GAAG,OAAO,CAAC,KAAK,MAAM,EAAE,CAAC;IA8CvG;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO;CA8BzC"}
+{"version":3,"file":"Invitations.d.ts","sourceRoot":"","sources":["../src/Invitations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAI1F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAgBnD,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,UAAU,CAAoB;IACtC,OAAO,CAAC,KAAK,CAAe;IAC5B,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,eAAe,CAAiC;gBAE5C,MAAM,EAAE,aAAa;IAsBjC;;;;;;;;OAQG;IACG,gBAAgB,CACpB,OAAO,EAAE,OAAO,EAChB,UAAU,EAAE,KAAK,MAAM,EAAE,GACxB,OAAO,CAAC,IAAI,CAAC;IAgChB;;;;;;;OAOG;IACG,aAAa,CACjB,OAAO,EAAE,OAAO,EAChB,KAAK,GAAE,MAAW,EAClB,MAAM,GAAE,MAAU,GACjB,OAAO,CAAC,mBAAmB,CAAC;IAiC/B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,iBAAiB;IAezB;;;;;;;;;;;;;;;;;OAiBG;IACG,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IA+CvF;;;;;;;;;;;OAWG;IACG,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,mBAAmB,CAAC,EAAE,OAAO;IA+CpE;;;;;;;;;;;;;;;;;OAiBG;IACG,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAwFhE;;;;;;;;;;;;;;OAcG;IACG,gBAAgB,CACpB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC;QAAE,YAAY,EAAE,kBAAkB,EAAE,CAAC;QAAC,UAAU,EAAE,KAAK,MAAM,EAAE,CAAA;KAAE,CAAC;IAiD7E;;;;;;;;;;;;;OAaG;IACG,kBAAkB,CAAC,SAAS,EAAE,OAAO,EAAE,EAAE,eAAe,GAAE,OAAc,GAAG,OAAO,CAAC,KAAK,MAAM,EAAE,CAAC;IA8CvG;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO;CA8BzC"}

package/dist/Invitations.js

@@ -0,0 +1,455 @@
+import { RpcClient, PathfinderMethods, TrustMethods } from '@aboutcircles/sdk-rpc';
+import { HubV2ContractMinimal, ReferralsModuleContractMinimal } from '@aboutcircles/sdk-core/minimal';
+import { InvitationError } from './errors';
+import { TransferBuilder } from '@aboutcircles/sdk-transfers';
+import { hexToBytes, INVITATION_FEE, MAX_FLOW, generatePrivateKey, privateKeyToAddress, encodeAbiParameters, keccak256, SAFE_PROXY_FACTORY, ACCOUNT_INITIALIZER_HASH, ACCOUNT_CREATION_CODE_HASH, checksumAddress } from '@aboutcircles/sdk-utils';
+/**
+ * Invitations handles invitation operations for Circles
+ * Supports both referral invitations (new users) and direct invitations (existing Safe wallets)
+ */
+export class Invitations {
+    config;
+    rpcClient;
+    pathfinder;
+    trust;
+    hubV2;
+    referralsModule;
+    constructor(config) {
+        if (!config.referralsServiceUrl) {
+            throw new InvitationError('referralsServiceUrl is required in config', {
+                code: 'INVITATION_MISSING_CONFIG',
+                source: 'INVITATIONS',
+                context: { missingField: 'referralsServiceUrl' }
+            });
+        }
+        this.config = config;
+        this.rpcClient = new RpcClient(config.circlesRpcUrl);
+        this.pathfinder = new PathfinderMethods(this.rpcClient);
+        this.trust = new TrustMethods(this.rpcClient);
+        this.hubV2 = new HubV2ContractMinimal({
+            address: config.v2HubAddress,
+            rpcUrl: config.circlesRpcUrl,
+        });
+        this.referralsModule = new ReferralsModuleContractMinimal({
+            address: config.referralsModuleAddress,
+            rpcUrl: config.circlesRpcUrl,
+        });
+    }
+    /**
+     * Save referral data to the referrals service
+     *
+     * @param inviter - Address of the inviter
+     * @param privateKey - Private key generated for the new user
+     *
+     * @description
+     * Sends a POST request to the referrals service to store referral data.
+     */
+    async saveReferralData(inviter, privateKey) {
+        try {
+            const response = await fetch(`${this.config.referralsServiceUrl}/store`, {
+                method: 'POST',
+                headers: {
+                    'accept': 'application/json',
+                    'Content-Type': 'application/json'
+                },
+                body: JSON.stringify({
+                    privateKey,
+                    inviter
+                })
+            });
+            if (!response.ok) {
+                throw new InvitationError(`HTTP error! status: ${response.status}`, {
+                    code: 'INVITATION_HTTP_ERROR',
+                    source: 'INVITATIONS',
+                    context: { status: response.status, url: `${this.config.referralsServiceUrl}/store` }
+                });
+            }
+        }
+        catch (error) {
+            console.error('Failed to save referral data:', error);
+            throw new InvitationError(`Failed to save referral data: ${error instanceof Error ? error.message : 'Unknown error'}`, {
+                code: 'INVITATION_SAVE_REFERRAL_FAILED',
+                source: 'INVITATIONS',
+                cause: error
+            });
+        }
+    }
+    /**
+     * List referrals for a given inviter with key previews
+     *
+     * @param inviter - Address of the inviter
+     * @param limit - Maximum number of referrals to return (default 10)
+     * @param offset - Number of referrals to skip for pagination (default 0)
+     * @returns Paginated list of referral previews with masked keys
+     */
+    async listReferrals(inviter, limit = 10, offset = 0) {
+        try {
+            const url = new URL(`${this.config.referralsServiceUrl}/referrals/list/${inviter}`);
+            url.searchParams.set('limit', String(limit));
+            url.searchParams.set('offset', String(offset));
+            const response = await fetch(url.toString(), {
+                method: 'GET',
+                headers: { 'accept': 'application/json' },
+            });
+            if (!response.ok) {
+                throw new InvitationError(`HTTP error! status: ${response.status}`, {
+                    code: 'INVITATION_HTTP_ERROR',
+                    source: 'INVITATIONS',
+                    context: { status: response.status, url: url.toString() },
+                });
+            }
+            return await response.json();
+        }
+        catch (error) {
+            if (error instanceof InvitationError)
+                throw error;
+            throw new InvitationError(`Failed to list referrals: ${error instanceof Error ? error.message : 'Unknown error'}`, {
+                code: 'INVITATION_LIST_REFERRALS_FAILED',
+                source: 'INVITATIONS',
+                cause: error,
+            });
+        }
+    }
+    /**
+     * Order real inviters by preference (best to worst)
+     *
+     * @param realInviters - Array of valid real inviters with their addresses and possible invites
+     * @param inviter - Address of the current inviter (prioritized first)
+     * @returns Ordered array of real inviters (best candidates first)
+     *
+     * @description
+     * This function determines the optimal order for selecting real inviters.
+     * Prioritizes the inviter's own tokens first, then others.
+     */
+    orderRealInviters(realInviters, inviter) {
+        const inviterLower = inviter.toLowerCase();
+        return realInviters.sort((a, b) => {
+            const aIsInviter = a.address.toLowerCase() === inviterLower;
+            const bIsInviter = b.address.toLowerCase() === inviterLower;
+            // Prioritize the inviter's own tokens first
+            if (aIsInviter && !bIsInviter)
+                return -1;
+            if (!aIsInviter && bIsInviter)
+                return 1;
+            return 0;
+        });
+    }
+    /**
+     * Generate invitation transaction for a user who already has a Safe wallet but is not yet registered in Circles Hub
+     *
+     * @param inviter - Address of the inviter
+     * @param invitee - Address of the invitee (must have an existing Safe wallet but NOT be registered in Circles Hub)
+     * @returns Array of transactions to execute in order
+     *
+     * @description
+     * This function:
+     * 1. Verifies the invitee is NOT already registered as a human in Circles Hub
+     * 2. Finds a path from inviter to invitation module using available proxy inviters
+     * 3. Generates invitation data for the existing Safe wallet address
+     * 4. Builds transaction batch with proper wrapped token handling
+     * 5. Returns transactions ready to execute
+     *
+     * Note: The invitee MUST have a Safe wallet but MUST NOT be registered in Circles Hub yet.
+     * If they are already registered, an error will be thrown.
+     */
+    async generateInvite(inviter, invitee) {
+        const inviterLower = inviter.toLowerCase();
+        const inviteeLower = invitee.toLowerCase();
+        // Step 1: Verify invitee is NOT already registered as a human in Circles Hub
+        const isHuman = await this.hubV2.isHuman(inviteeLower);
+        if (isHuman) {
+            throw InvitationError.inviteeAlreadyRegistered(inviterLower, inviteeLower);
+        }
+        // Step 2: Find path to invitation module using proxy inviters
+        const path = await this.findInvitePath(inviterLower);
+        // Step 3: Generate invitation data for existing Safe wallet
+        // For non-registered addresses (existing Safe wallets), we pass their address directly
+        // useSafeCreation = false because the invitee already has a Safe wallet
+        const transferData = await this.generateInviteData([inviteeLower], false);
+        // Step 4: Build transactions using TransferBuilder to properly handle wrapped tokens
+        const transferBuilder = new TransferBuilder(this.config);
+        // Get the real inviter address from the path
+        const realInviters = await this.getRealInviters(inviterLower);
+        if (realInviters.length === 0) {
+            throw InvitationError.noPathFound(inviterLower, this.config.invitationModuleAddress);
+        }
+        const realInviterAddress = realInviters[0].address;
+        // Use the buildFlowMatrixTx method to construct transactions from the path
+        const transferTransactions = await transferBuilder.buildFlowMatrixTx(inviterLower, this.config.invitationModuleAddress, path, {
+            toTokens: [realInviterAddress],
+            useWrappedBalances: true,
+            txData: hexToBytes(transferData)
+        }, true);
+        return transferTransactions;
+    }
+    /**
+     * Find a path from inviter to the invitation module for a specific proxy inviter
+     *
+     * @param inviter - Address of the inviter
+     * @param proxyInviterAddress - Optional specific proxy inviter address to use for the path
+     * @returns PathfindingResult containing the transfer path
+     *
+     * @description
+     * This function finds a path from the inviter to the invitation module.
+     * If proxyInviterAddress is provided, it will find a path using that specific token.
+     * Otherwise, it will use the first available proxy inviter.
+     */
+    async findInvitePath(inviter, proxyInviterAddress) {
+        const inviterLower = inviter.toLowerCase();
+        let tokenToUse;
+        if (proxyInviterAddress) {
+            tokenToUse = proxyInviterAddress.toLowerCase();
+        }
+        else {
+            // Get real inviters and use the first one
+            const realInviters = await this.getRealInviters(inviterLower);
+            if (realInviters.length === 0) {
+                throw InvitationError.noPathFound(inviterLower, this.config.invitationModuleAddress);
+            }
+            tokenToUse = realInviters[0].address;
+        }
+        // Find path using the selected token
+        const path = await this.pathfinder.findPath({
+            from: inviterLower,
+            to: this.config.invitationModuleAddress,
+            targetFlow: INVITATION_FEE,
+            toTokens: [tokenToUse],
+            useWrappedBalances: true
+        });
+        if (!path.transfers || path.transfers.length === 0) {
+            throw InvitationError.noPathFound(inviterLower, this.config.invitationModuleAddress);
+        }
+        if (path.maxFlow < INVITATION_FEE) {
+            const requestedInvites = 1;
+            const availableInvites = Number(path.maxFlow / INVITATION_FEE);
+            throw InvitationError.insufficientBalance(requestedInvites, availableInvites, INVITATION_FEE, path.maxFlow, inviterLower, this.config.invitationModuleAddress);
+        }
+        return path;
+    }
+    /**
+     * Get real inviters who have enough balance to cover invitation fees
+     *
+     * @param inviter - Address of the inviter
+     * @returns Array of real inviters with their addresses and possible number of invitations
+     *
+     * @description
+     * This function:
+     * 1. Gets all addresses that trust the inviter (set1) - includes both one-way trusts and mutual trusts
+     * 2. Gets all addresses trusted by the invitation module (set2) - includes both one-way trusts and mutual trusts
+     * 3. Finds the intersection of set1 and set2
+     * 4. Adds the inviter's own address to the list of possible tokens
+     * 5. Builds a path from inviter to invitation module using intersection addresses as toTokens
+     * 6. Sums up transferred token amounts by tokenOwner
+     * 7. Calculates possible invites (1 invite = 96 CRC)
+     * 8. Orders real inviters by preference (best candidates first)
+     * 9. Returns only those token owners whose total amounts exceed the invitation fee (96 CRC)
+     */
+    async getRealInviters(inviter) {
+        const inviterLower = inviter.toLowerCase();
+        // Step 1: Get addresses that trust the inviter (set1)
+        // This includes both one-way incoming trusts and mutual trusts
+        const trustedByRelations = await this.trust.getTrustedBy(inviterLower);
+        const mutualTrustRelations = await this.trust.getMutualTrusts(inviterLower);
+        // Extract the addresses of avatars who trust the inviter
+        // Combine both trustedBy (one-way) and mutualTrusts
+        const trustedByInviter = new Set([
+            ...trustedByRelations.map(relation => relation.objectAvatar.toLowerCase()),
+            ...mutualTrustRelations.map(relation => relation.objectAvatar.toLowerCase())
+        ]);
+        // Step 2: Get addresses trusted by the invitation module (set2)
+        // This includes both one-way outgoing trusts and mutual trusts
+        const trustsRelations = await this.trust.getTrusts(this.config.invitationModuleAddress);
+        const mutualTrustRelationsModule = await this.trust.getMutualTrusts(this.config.invitationModuleAddress);
+        const trustedByModule = new Set([
+            ...trustsRelations.map(relation => relation.objectAvatar.toLowerCase()),
+            ...mutualTrustRelationsModule.map(relation => relation.objectAvatar.toLowerCase())
+        ]);
+        // Step 3: Find intersection - addresses that trust inviter AND are trusted by invitation module
+        const intersection = [];
+        for (const address of trustedByInviter) {
+            if (trustedByModule.has(address)) {
+                intersection.push(address);
+            }
+        }
+        // Step 4: Add the inviter's own address to the list of possible tokens
+        // This allows the inviter to use their own personal tokens for invitations
+        const tokensToUse = [...intersection, inviterLower];
+        // If no tokens available at all, return empty
+        if (tokensToUse.length === 0) {
+            return [];
+        }
+        // Step 5: Build path from inviter to invitation module
+        const path = await this.pathfinder.findPath({
+            from: inviterLower,
+            to: this.config.invitationModuleAddress,
+            useWrappedBalances: true,
+            targetFlow: MAX_FLOW,
+            toTokens: tokensToUse,
+        });
+        if (!path.transfers || path.transfers.length === 0) {
+            return [];
+        }
+        // Step 6: Sum up transferred token amounts by tokenOwner (only terminal transfers to invitation module)
+        const tokenOwnerAmounts = new Map();
+        const invitationModuleLower = this.config.invitationModuleAddress.toLowerCase();
+        for (const transfer of path.transfers) {
+            // Only count transfers that go to the invitation module (terminal transfers)
+            if (transfer.to.toLowerCase() === invitationModuleLower) {
+                const tokenOwnerLower = transfer.tokenOwner.toLowerCase();
+                const currentAmount = tokenOwnerAmounts.get(tokenOwnerLower) || BigInt(0);
+                tokenOwnerAmounts.set(tokenOwnerLower, currentAmount + transfer.value);
+            }
+        }
+        // Step 7: Calculate possible invites and filter token owners
+        const realInviters = [];
+        for (const [tokenOwner, amount] of tokenOwnerAmounts.entries()) {
+            const possibleInvites = Number(amount / INVITATION_FEE);
+            if (possibleInvites >= 1) {
+                realInviters.push({
+                    address: tokenOwner,
+                    possibleInvites
+                });
+            }
+        }
+        // Step 8: Order real inviters by preference (best candidates first)
+        // Prioritizes the inviter's own tokens first
+        const orderedRealInviters = this.orderRealInviters(realInviters, inviterLower);
+        return orderedRealInviters;
+    }
+    /**
+     * Generate a referral for inviting a new user
+     *
+     * @param inviter - Address of the inviter
+     * @returns Object containing transactions and the generated private key
+     *
+     * @description
+     * This function:
+     * 1. Generates a new private key and signer address for the invitee
+     * 2. Finds a proxy inviter (someone who has balance and is trusted by both inviter and invitation module)
+     * 3. Builds transaction batch including transfers and invitation
+     * 4. Uses generateInviteData to properly encode the Safe account creation data
+     * 5. Saves the referral data (private key, signer, inviter) to database
+     * 6. Returns transactions and the generated private key
+     */
+    async generateReferral(inviter) {
+        const inviterLower = inviter.toLowerCase();
+        // Step 1: Generate private key and derive signer address
+        const privateKey = generatePrivateKey();
+        const signerAddress = privateKeyToAddress(privateKey);
+        // Step 2: Get real inviters
+        const realInviters = await this.getRealInviters(inviterLower);
+        if (realInviters.length === 0) {
+            throw InvitationError.noProxyInviters(inviterLower);
+        }
+        // Step 3: Pick the first real inviter
+        const firstRealInviter = realInviters[0];
+        const realInviterAddress = firstRealInviter.address;
+        // Step 4: Find path to invitation module
+        const path = await this.findInvitePath(inviterLower, realInviterAddress);
+        // Step 5: Build transactions using TransferBuilder to properly handle wrapped tokens
+        const transferBuilder = new TransferBuilder(this.config);
+        // useSafeCreation = true because we're creating a new Safe wallet via ReferralsModule
+        const transferData = await this.generateInviteData([signerAddress], true);
+        // Use the new buildFlowMatrixTx method to construct transactions from the path
+        const transferTransactions = await transferBuilder.buildFlowMatrixTx(inviterLower, this.config.invitationModuleAddress, path, {
+            toTokens: [realInviterAddress],
+            useWrappedBalances: true,
+            txData: hexToBytes(transferData)
+        }, true);
+        // Step 6: Save referral data to database
+        await this.saveReferralData(inviterLower, privateKey);
+        // Step 7: Build final transaction batch
+        const transactions = [];
+        transactions.push(...transferTransactions);
+        return { transactions, privateKey };
+    }
+    /**
+     * Generate invitation data based on whether addresses need Safe account creation or already have Safe wallets
+     *
+     * @param addresses - Array of addresses to check and encode
+     * @param useSafeCreation - If true, uses ReferralsModule to create Safe accounts (for new users without wallets)
+     * @returns Encoded data for the invitation transfer
+     *
+     * @description
+     * Two modes:
+     * 1. Direct invitation (useSafeCreation = false): Encodes addresses directly for existing Safe wallets
+     * 2. Safe creation (useSafeCreation = true): Uses ReferralsModule to create Safe accounts for new users
+     *
+     * Note: Addresses passed here should NEVER be registered humans in the hub (that's validated before calling this)
+     */
+    async generateInviteData(addresses, useSafeCreation = true) {
+        if (addresses.length === 0) {
+            throw InvitationError.noAddressesProvided();
+        }
+        // If NOT using Safe creation, encode addresses directly (for existing Safe wallets)
+        if (!useSafeCreation) {
+            if (addresses.length === 1) {
+                // Single address - encode as single address (not array)
+                return encodeAbiParameters(['address'], [addresses[0]]);
+            }
+            else {
+                // Multiple addresses - encode as address array
+                return encodeAbiParameters(['address[]'], [addresses]);
+            }
+        }
+        // Use ReferralsModule to create Safe accounts for new users (signers without Safe wallets)
+        if (addresses.length === 1) {
+            // Single address - use createAccount(address signer)
+            const createAccountTx = this.referralsModule.createAccount(addresses[0]);
+            const createAccountData = createAccountTx.data;
+            // Encode (address target, bytes callData) for the invitation module
+            return encodeAbiParameters(['address', 'bytes'], [this.config.referralsModuleAddress, createAccountData]);
+        }
+        else {
+            // Multiple addresses - use createAccounts(address[] signers)
+            const createAccountsTx = this.referralsModule.createAccounts(addresses);
+            const createAccountsData = createAccountsTx.data;
+            // Encode (address target, bytes callData) for the invitation module
+            return encodeAbiParameters(['address', 'bytes'], [this.config.referralsModuleAddress, createAccountsData]);
+        }
+    }
+    /**
+     * Predicts the pre-made Safe address for a given signer without deploying it
+     * Uses CREATE2 with ACCOUNT_INITIALIZER_HASH and ACCOUNT_CREATION_CODE_HASH via SAFE_PROXY_FACTORY
+     *
+     * @param signer - The offchain public address chosen by the origin inviter as the pre-deployment key
+     * @returns The deterministic Safe address that would be deployed for the signer
+     *
+     * @description
+     * This implements the same logic as the ReferralsModule.computeAddress() contract function:
+     * ```solidity
+     * bytes32 salt = keccak256(abi.encodePacked(ACCOUNT_INITIALIZER_HASH, uint256(uint160(signer))));
+     * predictedAddress = address(
+     *   uint160(
+     *     uint256(
+     *       keccak256(
+     *         abi.encodePacked(bytes1(0xff), address(SAFE_PROXY_FACTORY), salt, ACCOUNT_CREATION_CODE_HASH)
+     *       )
+     *     )
+     *   )
+     * );
+     * ```
+     */
+    computeAddress(signer) {
+        // Step 1: Calculate salt = keccak256(abi.encodePacked(ACCOUNT_INITIALIZER_HASH, uint256(uint160(signer))))
+        // abi.encodePacked means concatenate without padding
+        // uint256(uint160(signer)) converts address to uint256 (32 bytes, left-padded with zeros)
+        const signerLower = signer.toLowerCase().replace('0x', '');
+        const signerUint256 = signerLower.padStart(64, '0'); // 32 bytes as hex string
+        // Concatenate: ACCOUNT_INITIALIZER_HASH (32 bytes) + signerUint256 (32 bytes)
+        const saltPreimage = ACCOUNT_INITIALIZER_HASH.replace('0x', '') + signerUint256;
+        const salt = keccak256(('0x' + saltPreimage));
+        // Step 2: Calculate CREATE2 address
+        // address = keccak256(0xff ++ factory ++ salt ++ initCodeHash)[12:]
+        const ff = 'ff';
+        const factory = SAFE_PROXY_FACTORY.toLowerCase().replace('0x', '');
+        const saltClean = salt.replace('0x', '');
+        const initCodeHash = ACCOUNT_CREATION_CODE_HASH.replace('0x', '');
+        // Concatenate all parts
+        const create2Preimage = ff + factory + saltClean + initCodeHash;
+        const hash = keccak256(('0x' + create2Preimage));
+        // Take last 20 bytes (40 hex chars) as the address
+        const addressHex = '0x' + hash.slice(-40);
+        return checksumAddress(addressHex);
+    }
+}

package/dist/InviteFarm.d.ts

@@ -0,0 +1,59 @@
+import type { Address, CirclesConfig, TransactionRequest, Hex } from '@aboutcircles/sdk-types';
+import type { ReferralPreviewList } from './types';
+export interface GeneratedInvite {
+    secret: Hex;
+    signer: Address;
+}
+export interface GenerateInvitesResult {
+    invites: GeneratedInvite[];
+    transactions: TransactionRequest[];
+}
+/**
+ * InviteFarm handles batch invitation generation via the InvitationFarm contract
+ *
+ * This class provides methods to generate multiple invitations at once using
+ * the InvitationFarm contract, which manages a farm of InvitationBot instances.
+ */
+export declare class InviteFarm {
+    private config;
+    private invitations;
+    private invitationFarm;
+    private referralsModule;
+    private hubV2;
+    constructor(config: CirclesConfig);
+    /**
+     * Get the remaining invite quota for a specific inviter
+     */
+    getQuota(inviter: Address): Promise<bigint>;
+    /**
+     * Get the invitation fee (96 CRC)
+     */
+    getInvitationFee(): Promise<bigint>;
+    /**
+     * Get the invitation module address from the farm
+     */
+    getInvitationModule(): Promise<Address>;
+    /**
+     * Generate batch invitations using the InvitationFarm
+     *
+     * This method:
+     * 1. Simulates claimInvites to get token IDs that will be claimed
+     * 2. Generates random secrets and derives signer addresses
+     * 3. Builds transaction batch: claimInvites + safeBatchTransferFrom
+     *
+     * @param inviter - Address of the inviter (must have quota)
+     * @param count - Number of invitations to generate
+     * @returns Generated invites with secrets/signers and transactions to execute
+     */
+    generateInvites(inviter: Address, count: number): Promise<GenerateInvitesResult>;
+    /**
+     * List referrals for a given inviter with key previews
+     *
+     * @param inviter - Address of the inviter
+     * @param limit - Maximum number of referrals to return (default 10)
+     * @param offset - Number of referrals to skip for pagination (default 0)
+     * @returns Paginated list of referral previews with masked keys
+     */
+    listReferrals(inviter: Address, limit?: number, offset?: number): Promise<ReferralPreviewList>;
+}
+//# sourceMappingURL=InviteFarm.d.ts.map

package/dist/InviteFarm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InviteFarm.d.ts","sourceRoot":"","sources":["../src/InviteFarm.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,GAAG,EAAE,MAAM,yBAAyB,CAAC;AAO/F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AASnD,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,GAAG,CAAC;IACZ,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,YAAY,EAAE,kBAAkB,EAAE,CAAC;CACpC;AAED;;;;;GAKG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,cAAc,CAAgC;IACtD,OAAO,CAAC,eAAe,CAAiC;IACxD,OAAO,CAAC,KAAK,CAAuB;gBAExB,MAAM,EAAE,aAAa;IAiBjC;;OAEG;IACG,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC;IAIjD;;OAEG;IACG,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC;IAIzC;;OAEG;IACG,mBAAmB,IAAI,OAAO,CAAC,OAAO,CAAC;IAI7C;;;;;;;;;;;OAWG;IACG,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IA0EtF;;;;;;;OAOG;IACG,aAAa,CACjB,OAAO,EAAE,OAAO,EAChB,KAAK,GAAE,MAAW,EAClB,MAAM,GAAE,MAAU,GACjB,OAAO,CAAC,mBAAmB,CAAC;CAGhC"}

package/dist/InviteFarm.js

@@ -0,0 +1,123 @@
+import { InvitationFarmContractMinimal, ReferralsModuleContractMinimal, HubV2ContractMinimal } from '@aboutcircles/sdk-core/minimal';
+import { InvitationError } from './errors';
+import { Invitations } from './Invitations';
+import { generatePrivateKey, privateKeyToAddress, encodeAbiParameters, INVITATION_FEE } from '@aboutcircles/sdk-utils';
+/**
+ * InviteFarm handles batch invitation generation via the InvitationFarm contract
+ *
+ * This class provides methods to generate multiple invitations at once using
+ * the InvitationFarm contract, which manages a farm of InvitationBot instances.
+ */
+export class InviteFarm {
+    config;
+    invitations;
+    invitationFarm;
+    referralsModule;
+    hubV2;
+    constructor(config) {
+        this.config = config;
+        this.invitations = new Invitations(config);
+        this.invitationFarm = new InvitationFarmContractMinimal({
+            address: config.invitationFarmAddress,
+            rpcUrl: config.circlesRpcUrl,
+        });
+        this.referralsModule = new ReferralsModuleContractMinimal({
+            address: config.referralsModuleAddress,
+            rpcUrl: config.circlesRpcUrl,
+        });
+        this.hubV2 = new HubV2ContractMinimal({
+            address: config.v2HubAddress,
+            rpcUrl: config.circlesRpcUrl,
+        });
+    }
+    /**
+     * Get the remaining invite quota for a specific inviter
+     */
+    async getQuota(inviter) {
+        return this.invitationFarm.inviterQuota(inviter);
+    }
+    /**
+     * Get the invitation fee (96 CRC)
+     */
+    async getInvitationFee() {
+        return this.invitationFarm.invitationFee();
+    }
+    /**
+     * Get the invitation module address from the farm
+     */
+    async getInvitationModule() {
+        return this.invitationFarm.invitationModule();
+    }
+    /**
+     * Generate batch invitations using the InvitationFarm
+     *
+     * This method:
+     * 1. Simulates claimInvites to get token IDs that will be claimed
+     * 2. Generates random secrets and derives signer addresses
+     * 3. Builds transaction batch: claimInvites + safeBatchTransferFrom
+     *
+     * @param inviter - Address of the inviter (must have quota)
+     * @param count - Number of invitations to generate
+     * @returns Generated invites with secrets/signers and transactions to execute
+     */
+    async generateInvites(inviter, count) {
+        if (count <= 0) {
+            throw new InvitationError('Count must be greater than 0', {
+                code: 'INVITATION_INVALID_COUNT',
+                source: 'VALIDATION',
+                context: { count },
+            });
+        }
+        const inviterLower = inviter.toLowerCase();
+        const numberOfInvites = BigInt(count);
+        // Step 1: Simulate claimInvites to get token IDs
+        const ids = await this.invitationFarm.read('claimInvites', [numberOfInvites], {
+            from: inviterLower
+        });
+        if (!ids || ids.length === 0) {
+            throw new InvitationError('No invitation IDs returned from claimInvites', {
+                code: 'INVITATION_NO_IDS',
+                source: 'INVITATIONS',
+                context: { inviter: inviterLower, count },
+            });
+        }
+        // Step 2: Generate secrets and signers
+        const invites = [];
+        const signers = [];
+        for (let i = 0; i < count; i++) {
+            const secret = generatePrivateKey();
+            const signer = privateKeyToAddress(secret).toLowerCase();
+            invites.push({ secret, signer });
+            signers.push(signer);
+        }
+        // Step 3: Get addresses
+        const invitationModuleAddress = await this.invitationFarm.invitationModule();
+        // Step 4: Build transactions
+        const claimTx = this.invitationFarm.claimInvites(numberOfInvites);
+        // Encode createAccounts call
+        const createAccountsTx = this.referralsModule.createAccounts(signers);
+        const createAccountsData = createAccountsTx.data;
+        // Encode data for safeBatchTransferFrom
+        const encodedData = encodeAbiParameters(['address', 'bytes'], [this.config.referralsModuleAddress, createAccountsData]);
+        // Build amounts array (96 CRC per invite)
+        const amounts = ids.map(() => INVITATION_FEE);
+        const batchTransferTx = this.hubV2.safeBatchTransferFrom(inviterLower, invitationModuleAddress, ids, amounts, encodedData);
+        // Save all referrals to database
+        await Promise.all(invites.map((inv) => this.invitations.saveReferralData(inviterLower, inv.secret)));
+        return {
+            invites,
+            transactions: [claimTx, batchTransferTx],
+        };
+    }
+    /**
+     * List referrals for a given inviter with key previews
+     *
+     * @param inviter - Address of the inviter
+     * @param limit - Maximum number of referrals to return (default 10)
+     * @param offset - Number of referrals to skip for pagination (default 0)
+     * @returns Paginated list of referral previews with masked keys
+     */
+    async listReferrals(inviter, limit = 10, offset = 0) {
+        return this.invitations.listReferrals(inviter, limit, offset);
+    }
+}