@aboutcircles/sdk 0.1.0 → 0.1.2

package/README.md

@@ -203,27 +203,23 @@ await sdk.profiles.createOrUpdate({
 
 ## Implementation Status
 
-⚠️ **Note**: This package is currently a skeleton implementation. Most methods throw "Not yet implemented" errors and are marked with TODO comments. The purpose is to establish the API surface for future implementation.
+✅ **Status**: This SDK is feature-complete and production-ready. All core functionality has been implemented.
 
 ### Implemented Features
 
 - ✅ SDK initialization with configuration
-- ✅ Avatar retrieval (getAvatar)
-- ✅ Profile retrieval by CID (via profiles package)
-
-### Not Yet Implemented
-
-Most features are marked with TODO and will throw errors:
-
-- Registration methods (asHuman, asOrganization, asGroup)
-- Balance operations
-- Transfer operations
-- Trust operations
-- Personal token minting
-- Profile updates
-- Group operations
-- Token wrapping
-- Event streaming
+- ✅ Avatar retrieval and type detection (getAvatar)
+- ✅ Registration methods (asHuman, asOrganization, asGroup)
+- ✅ Balance operations (total, detailed token balances)
+- ✅ Transfer operations (direct transfers, pathfinding with advanced options)
+- ✅ Trust operations (add, remove, check trust status)
+- ✅ Personal token minting and management
+- ✅ Profile management (get, update, metadata, short names)
+- ✅ Group operations (members, holders, collateral, treasury)
+- ✅ Token wrapping (demurraged and inflationary ERC20)
+- ✅ Event subscriptions and streaming
+- ✅ Transaction history
+- ✅ Profile creation and management via IPFS
 
 ## Architecture
 
@@ -237,12 +233,13 @@ The SDK package wraps and simplifies the following packages:
 
 ## Contributing
 
-To implement a method:
+To extend or improve the SDK:
 
-1. Remove the "TODO" comment
-2. Replace the `throw new Error('not yet implemented')` with actual implementation
-3. Use the underlying packages (core, rpc, profiles, etc.) to implement functionality
-4. Add tests and update documentation
+1. Update existing methods or add new features as needed
+2. Leverage the underlying packages (core, rpc, profiles, transfers, etc.)
+3. Add tests and update documentation
+4. Ensure all changes maintain backward compatibility
+5. Follow the established patterns and code style in the SDK
 
 ## License
 

package/dist/Sdk.d.ts

@@ -48,9 +48,13 @@ export declare class Sdk {
     /**
      * Get an avatar by address
      * Automatically detects the avatar type and returns the appropriate avatar instance
+     *
+     * @param avatarAddress The address of the avatar to fetch
+     * @param autoSubscribeEvents Whether to automatically subscribe to events for this avatar (default: false)
+     *                            If true, waits for event subscription to complete before returning
      * @returns HumanAvatar, OrganisationAvatar, or BaseGroupAvatar depending on type
      */
-    getAvatar(avatarAddress: Address): Promise<HumanAvatar | OrganisationAvatar | BaseGroupAvatar>;
+    getAvatar(avatarAddress: Address, autoSubscribeEvents?: boolean): Promise<HumanAvatar | OrganisationAvatar | BaseGroupAvatar>;
     /**
      * Registration methods for creating new Circles identities
      */

package/dist/Sdk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Sdk.d.ts","sourceRoot":"","sources":["../src/Sdk.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EACP,aAAa,EACb,cAAc,EACd,OAAO,EAEP,YAAY,EACZ,SAAS,EAEV,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,EAAiB,IAAI,EAAkC,MAAM,wBAAwB,CAAC;AAE7F,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAE/D,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAI7E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAG3C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,qBAAa,GAAG;IACd,SAAgB,aAAa,EAAE,aAAa,CAAC;IAC7C,SAAgB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChD,SAAgB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxC,SAAgB,IAAI,EAAE,IAAI,CAAC;IAC3B,SAAgB,GAAG,EAAE,UAAU,CAAC;IAChC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAW;IAE1C,SAAgB,IAAI,EAAE,WAAW,CAU/B;IAEF;;;;;;OAMG;gBACS,MAAM,GAAE,aAAkC,EAAE,cAAc,CAAC,EAAE,cAAc;IAsBvF;;;;OAIG;IACG,SAAS,CAAC,aAAa,EAAE,OAAO,GAAG,OAAO,CAAC,WAAW,GAAG,kBAAkB,GAAG,eAAe,CAAC;IAsBpG;;OAEG;IACH,SAAgB,QAAQ;QACtB;;;;;;;;;;;;;;;;;;;;;;;;;;WA0BG;2BAEQ,OAAO,WACP,OAAO,GAAG,MAAM,KACxB,OAAO,CAAC,WAAW,CAAC;QAqEvB;;;;;;;;;;;;;;;WAeG;kCAC6B,OAAO,GAAG,MAAM,KAAG,OAAO,CAAC,kBAAkB,CAAC;QAqD9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;WA4BG;yBAEM,OAAO,WACL,OAAO,iBACD,OAAO,qBACH,OAAO,EAAE,QACtB,MAAM,UACJ,MAAM,WACL,OAAO,GAAG,MAAM,KACxB,OAAO,CAAC,eAAe,CAAC;MAsF3B;IAEF;;OAEG;IACH,SAAgB,QAAQ;QACtB;;;;WAIG;0BACqB,OAAO,KAAG,OAAO,CAAC,MAAM,CAAC;QAIjD;;;;WAIG;mBACc,MAAM,KAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC;MAGtD;IAEF;;OAEG;IACH,SAAgB,MAAM;QACpB;;;;WAIG;0CACqC,OAAO,KAAG,OAAO,CAAC,OAAO,CAAC;QAIlE;;;;WAIG;wCACmC,OAAO,KAAG,OAAO,CAAC,OAAO,CAAC;QAIhE;;;;;;;;;;;;;;;;;;;WAmBG;mCAEa,OAAO,UACd,MAAM,cACF,SAAS;MAItB;IAEF;;OAEG;IACH,SAAgB,MAAM;QACpB;;;;WAIG;0BACqB,OAAO,KAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;QAIhE;;;;;;;;;;;;;;;;;;;;;;;;;;;WA2BG;mCAEa,OAAO,UACd,MAAM,cACF,KAAK,GAAG,MAAM;QAK3B;;;;;;;;;;;;;;;;;;;WAmBG;sCACiC,OAAO,KAAG,OAAO,CAAC,YAAY,EAAE,CAAC;QAcrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WA6BG;mCACwB,OAAO,UAAS,MAAM,KAAS,UAAU,CAAC,mBAAmB,CAAC;MAGzF;CACH"}
+{"version":3,"file":"Sdk.d.ts","sourceRoot":"","sources":["../src/Sdk.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EACP,aAAa,EACb,cAAc,EACd,OAAO,EAEP,YAAY,EACZ,SAAS,EAEV,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,EAAiB,IAAI,EAAkC,MAAM,wBAAwB,CAAC;AAE7F,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAE/D,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAI7E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAG3C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,qBAAa,GAAG;IACd,SAAgB,aAAa,EAAE,aAAa,CAAC;IAC7C,SAAgB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChD,SAAgB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxC,SAAgB,IAAI,EAAE,IAAI,CAAC;IAC3B,SAAgB,GAAG,EAAE,UAAU,CAAC;IAChC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAW;IAE1C,SAAgB,IAAI,EAAE,WAAW,CAU/B;IAEF;;;;;;OAMG;gBACS,MAAM,GAAE,aAAkC,EAAE,cAAc,CAAC,EAAE,cAAc;IAsBvF;;;;;;;;OAQG;IACG,SAAS,CAAC,aAAa,EAAE,OAAO,EAAE,mBAAmB,GAAE,OAAe,GAAG,OAAO,CAAC,WAAW,GAAG,kBAAkB,GAAG,eAAe,CAAC;IA+B1I;;OAEG;IACH,SAAgB,QAAQ;QACtB;;;;;;;;;;;;;;;;;;;;;;;;;;WA0BG;2BAEQ,OAAO,WACP,OAAO,GAAG,MAAM,KACxB,OAAO,CAAC,WAAW,CAAC;QAqEvB;;;;;;;;;;;;;;;WAeG;kCAC6B,OAAO,GAAG,MAAM,KAAG,OAAO,CAAC,kBAAkB,CAAC;QAqD9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;WA4BG;yBAEM,OAAO,WACL,OAAO,iBACD,OAAO,qBACH,OAAO,EAAE,QACtB,MAAM,UACJ,MAAM,WACL,OAAO,GAAG,MAAM,KACxB,OAAO,CAAC,eAAe,CAAC;MAsF3B;IAEF;;OAEG;IACH,SAAgB,QAAQ;QACtB;;;;WAIG;0BACqB,OAAO,KAAG,OAAO,CAAC,MAAM,CAAC;QAIjD;;;;WAIG;mBACc,MAAM,KAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC;MAGtD;IAEF;;OAEG;IACH,SAAgB,MAAM;QACpB;;;;WAIG;0CACqC,OAAO,KAAG,OAAO,CAAC,OAAO,CAAC;QAIlE;;;;WAIG;wCACmC,OAAO,KAAG,OAAO,CAAC,OAAO,CAAC;QAIhE;;;;;;;;;;;;;;;;;;;WAmBG;mCAEa,OAAO,UACd,MAAM,cACF,SAAS;MAItB;IAEF;;OAEG;IACH,SAAgB,MAAM;QACpB;;;;WAIG;0BACqB,OAAO,KAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;QAIhE;;;;;;;;;;;;;;;;;;;;;;;;;;;WA2BG;mCAEa,OAAO,UACd,MAAM,cACF,KAAK,GAAG,MAAM;QAK3B;;;;;;;;;;;;;;;;;;;WAmBG;sCACiC,OAAO,KAAG,OAAO,CAAC,YAAY,EAAE,CAAC;QAcrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WA6BG;mCACwB,OAAO,UAAS,MAAM,KAAS,UAAU,CAAC,mBAAmB,CAAC;MAGzF;CACH"}

package/dist/Sdk.js

@@ -78,21 +78,35 @@ export class Sdk {
     /**
      * Get an avatar by address
      * Automatically detects the avatar type and returns the appropriate avatar instance
+     *
+     * @param avatarAddress The address of the avatar to fetch
+     * @param autoSubscribeEvents Whether to automatically subscribe to events for this avatar (default: false)
+     *                            If true, waits for event subscription to complete before returning
      * @returns HumanAvatar, OrganisationAvatar, or BaseGroupAvatar depending on type
      */
-    async getAvatar(avatarAddress) {
+    async getAvatar(avatarAddress, autoSubscribeEvents = false) {
         try {
             const avatarInfo = await this.rpc.avatar.getAvatarInfo(avatarAddress);
             // Detect avatar type and return appropriate avatar class
             const avatarType = avatarInfo?.type;
+            let avatar;
             if (avatarType === 'CrcV2_RegisterGroup') {
-                return new BaseGroupAvatar(avatarAddress, this.core, this.contractRunner, avatarInfo);
+                avatar = new BaseGroupAvatar(avatarAddress, this.core, this.contractRunner, avatarInfo);
+            }
+            else if (avatarType === 'CrcV2_RegisterOrganization') {
+                avatar = new OrganisationAvatar(avatarAddress, this.core, this.contractRunner, avatarInfo);
+            }
+            else {
+                // Default to HumanAvatar for human type
+                avatar = new HumanAvatar(avatarAddress, this.core, this.contractRunner, avatarInfo);
             }
-            if (avatarType === 'CrcV2_RegisterOrganization') {
-                return new OrganisationAvatar(avatarAddress, this.core, this.contractRunner, avatarInfo);
+            // If auto-subscription is enabled, wait for it to complete before returning
+            // This prevents race conditions where stores subscribe to avatar.events before it's ready
+            if (autoSubscribeEvents) {
+                console.log('🔔 Sdk.getAvatar: Auto-subscribing to events for', avatarAddress);
+                await avatar.subscribeToEvents();
             }
-            // Default to HumanAvatar for human type
-            return new HumanAvatar(avatarAddress, this.core, this.contractRunner, avatarInfo);
+            return avatar;
         }
         catch (error) {
             throw SdkError.avatarNotFound(avatarAddress);

package/dist/avatars/CommonAvatar.d.ts

@@ -33,6 +33,7 @@ export declare abstract class CommonAvatar {
     protected _cachedProfile?: Profile;
     protected _cachedProfileCid?: string;
     protected _eventSubscription?: () => void;
+    private _hasSubscribed;
     constructor(address: Address, core: Core, contractRunner?: ContractRunner, avatarInfo?: AvatarRow);
     readonly balances: {
         /**
@@ -365,6 +366,7 @@ export declare abstract class CommonAvatar {
     /**
      * Subscribe to Circles events for this avatar
      * Events are filtered to only include events related to this avatar's address
+     * This method is idempotent - calling it multiple times will not create duplicate subscriptions
      *
      * @returns Promise that resolves when subscription is established
      *

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

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

package/dist/avatars/CommonAvatar.js

@@ -29,6 +29,7 @@ export class CommonAvatar {
     _cachedProfile;
     _cachedProfileCid;
     _eventSubscription;
+    _hasSubscribed = false;
     constructor(address, core, contractRunner, avatarInfo) {
         this.address = address;
         this.core = core;
@@ -49,6 +50,7 @@ export class CommonAvatar {
         // Initialize transfer builder
         this.transferBuilder = new TransferBuilder(core);
         // Event subscription is optional - initialize with stub observable
+        // Actual subscription is handled by Sdk.getAvatar() when autoSubscribeEvents is enabled
         const stub = ObservableClass.create();
         this.events = stub.property;
     }
@@ -565,6 +567,7 @@ export class CommonAvatar {
     /**
      * Subscribe to Circles events for this avatar
      * Events are filtered to only include events related to this avatar's address
+     * This method is idempotent - calling it multiple times will not create duplicate subscriptions
      *
      * @returns Promise that resolves when subscription is established
      *
@@ -583,9 +586,21 @@ export class CommonAvatar {
      * ```
      */
     async subscribeToEvents() {
-        // Subscribe to events via RPC WebSocket
-        const observable = await this.rpc.client.subscribe(this.address);
-        this.events = observable;
+        // Make idempotent - only subscribe once
+        if (this._hasSubscribed) {
+            return;
+        }
+        this._hasSubscribed = true;
+        try {
+            // Subscribe to events via RPC WebSocket
+            const observable = await this.rpc.client.subscribe(this.address);
+            this.events = observable;
+        }
+        catch (e) {
+            // Reset flag on error so it can be retried
+            this._hasSubscribed = false;
+            throw SdkError.operationFailed('subscribeToEvents', 'Failed to subscribe to avatar events', e);
+        }
     }
     /**
      * Unsubscribe from events

package/dist/avatars/HumanAvatar.d.ts

@@ -1,5 +1,5 @@
 import type { Address, AvatarRow, ContractRunner, TokenBalanceRow, GroupMembershipRow, GroupRow } from '@aboutcircles/sdk-types';
-import type { TransactionReceipt } from 'viem';
+import type { TransactionReceipt, Hex } from 'viem';
 import type { Core } from '@aboutcircles/sdk-core';
 import { CommonAvatar, type PathfindingOptions } from './CommonAvatar';
 /**
@@ -175,6 +175,43 @@ export declare class HumanAvatar extends CommonAvatar {
          * ```
          */
         getEscrowedAmount: (inviter: Address, invitee: Address) => Promise<import("@aboutcircles/sdk-types").EscrowedAmountAndDays>;
+        /**
+         * 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]}`);
+         * });
+         * ```
+         */
+        generateInvites: (numberOfInvites: bigint) => Promise<{
+            secrets: Hex[];
+            signers: Address[];
+            transactionReceipt: TransactionReceipt;
+        }>;
     };
     readonly personalToken: {
         /**

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

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

package/dist/avatars/HumanAvatar.js

@@ -1,7 +1,9 @@
 import { ValidationError } from '@aboutcircles/sdk-utils';
 import { SdkError } from '../errors';
 import { BaseGroupContract } from '@aboutcircles/sdk-core';
-import { encodeAbiParameters, parseAbiParameters } from 'viem';
+import { encodeAbiParameters, parseAbiParameters, encodeFunctionData } from 'viem';
+import { referralsModuleAbi } from '@aboutcircles/sdk-abis';
+import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts';
 import { CommonAvatar } from './CommonAvatar';
 /**
  * HumanAvatar class implementation
@@ -246,6 +248,100 @@ export class HumanAvatar extends CommonAvatar {
         getEscrowedAmount: async (inviter, invitee) => {
             return await this.core.invitationEscrow.getEscrowedAmountAndDays(inviter, invitee);
         },
+        /**
+         * 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]}`);
+         * });
+         * ```
+         */
+        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,
+            };
+        },
     };
     // Personal token / Minting methods
     personalToken = {