@aboutcircles/sdk-invitations 0.1.9 → 0.1.11

package/README.md

@@ -0,0 +1,159 @@
+# @aboutcircles/sdk-invitations
+
+Invitation package for Circles protocol. Create referrals for new users or invite existing Safe wallet users.
+
+## Installation
+
+```bash
+npm install @aboutcircles/sdk-invitations
+```
+
+## Usage
+
+```typescript
+import { Invitations, Referrals } from '@aboutcircles/sdk-invitations';
+import { circlesConfig } from '@aboutcircles/sdk-utils';
+
+const invitations = new Invitations(circlesConfig[100]);
+const referrals = new Referrals('https://referrals.circles.example');
+```
+
+---
+
+## API Reference
+
+### Invitations
+
+#### `constructor(config: CirclesConfig)`
+
+Initialize the Invitations client.
+
+---
+
+#### `generateReferral(inviter: Address)`
+
+Generate a new referral for a user without a Safe wallet.
+
+```typescript
+Promise<{
+  transactions: TransactionRequest[];
+  privateKey: `0x${string}`;
+}>
+```
+
+Creates a new private key, generates a Safe wallet via ReferralsModule, and saves to referrals service.
+
+---
+
+#### `generateInvite(inviter: Address, invitee: Address)`
+
+Invite a user who has a Safe wallet but isn't registered in Circles Hub.
+
+```typescript
+Promise<TransactionRequest[]>
+```
+
+---
+
+#### `getRealInviters(inviter: Address)`
+
+Get addresses whose tokens can pay for invitations.
+
+```typescript
+Promise<ProxyInviter[]>
+
+interface ProxyInviter {
+  address: Address;
+  possibleInvites: number;
+}
+```
+
+---
+
+#### `findInvitePath(inviter: Address, proxyInviterAddress?: Address)`
+
+Find path from inviter to invitation module.
+
+```typescript
+Promise<PathfindingResult>
+```
+
+---
+
+#### `generateInviteData(addresses: Address[], useSafeCreation: boolean)`
+
+Generate encoded invitation data for transactions.
+
+```typescript
+Promise<`0x${string}`>
+```
+
+- `useSafeCreation = true`: Creates Safe via ReferralsModule
+- `useSafeCreation = false`: Uses existing Safe addresses
+
+---
+
+#### `computeAddress(signer: Address)`
+
+Predict Safe address for a signer using CREATE2.
+
+```typescript
+Address
+```
+
+---
+
+### Referrals
+
+#### `constructor(baseUrl: string, getToken?: () => Promise<string>)`
+
+Initialize the Referrals service client.
+
+---
+
+#### `retrieve(privateKey: string)`
+
+Get referral information by private key (public endpoint).
+
+```typescript
+Promise<ReferralInfo>
+
+interface ReferralInfo {
+  inviter: string;
+  status: "pending" | "confirmed" | "claimed" | "expired";
+  accountAddress?: string;
+}
+```
+
+---
+
+#### `listMine()`
+
+List all referrals created by authenticated user.
+
+```typescript
+Promise<ReferralList>
+
+interface ReferralList {
+  referrals: Referral[];
+  count: number;
+}
+
+interface Referral {
+  id: string;
+  privateKey: string;
+  status: "pending" | "confirmed" | "claimed" | "expired";
+  accountAddress?: string;
+  createdAt: string;
+  confirmedAt: string | null;
+  claimedAt: string | null;
+}
+```
+
+Requires authentication via `getToken` function.
+
+---
+
+## License
+
+MIT

package/dist/{InvitationBuilder.d.ts → Invitations.d.ts}

@@ -1,13 +1,14 @@
 import type { Address, TransactionRequest, CirclesConfig } from '@aboutcircles/sdk-types';
+import type { ReferralPreviewList } from './types';
 export interface ProxyInviter {
     address: Address;
     possibleInvites: number;
 }
 /**
- * InvitationBuilder handles invitation operations for Circles
+ * Invitations handles invitation operations for Circles
  * Supports both referral invitations (new users) and direct invitations (existing Safe wallets)
  */
-export declare class InvitationBuilder {
+export declare class Invitations {
     private config;
     private rpcClient;
     private pathfinder;
@@ -24,7 +25,16 @@ export declare class InvitationBuilder {
      * @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)
      *
@@ -92,7 +102,7 @@ export declare class InvitationBuilder {
      * Generate a referral for inviting a new user
      *
      * @param inviter - Address of the inviter
-     * @returns Array of transactions to execute in order
+     * @returns Object containing transactions and the generated private key
      *
      * @description
      * This function:
@@ -101,12 +111,12 @@ export declare class InvitationBuilder {
      * 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 ready to execute
-     *
-     * Note: The private key is saved via saveReferralData and not returned.
-     * Retrieve it from the database using the inviter and signer addresses.
+     * 6. Returns transactions and the generated private key
      */
-    generateReferral(inviter: Address): Promise<TransactionRequest[]>;
+    generateReferral(inviter: Address): Promise<{
+        transactions: TransactionRequest[];
+        privateKey: `0x${string}`;
+    }>;
     /**
      * Generate invitation data based on whether addresses need Safe account creation or already have Safe wallets
      *
@@ -146,4 +156,4 @@ export declare class InvitationBuilder {
      */
     computeAddress(signer: Address): Address;
 }
-//# sourceMappingURL=InvitationBuilder.d.ts.map
+//# sourceMappingURL=Invitations.d.ts.map

package/dist/Invitations.d.ts.map

@@ -0,0 +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;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);
+    }
+}