Implementation

SDK implementation guide.

1. Install the package

pnpm add @argent/invisible-sdk

2. Import dependencies in your project

import { ArgentWebWallet, SessionAccountInterface } from '@argent/invisible-sdk';

3. Initialize the web wallet object with your app configuration:

const argentWebWallet = ArgentWebWallet.init({
  environment: "sepolia", // "sepolia" | "mainnet" (Whitelisting required)
  appName: "My App", // Your app name
  sessionParams: {
    allowedMethods: [
      // List of contracts/methods allowed to be called by the session key
      {
        contract:
          "0x036133c88c1954413150db74c26243e2af77170a4032934b275708d84ec5452f", // contract address
        selector: "increment", //function selector
      }
    ],
    validityDays: 30 // optional - session validity (in days) - default: 30
  },
  paymasterParams: {
    apiKey: "avnu paymaster api key" 
  }
});

To use session keys on mainnet, you will need to whitelist your contract with us. Please reach out.

4. Paymaster

Ready will automatically sponsor the deployment of accounts but you might want to sponsor additional transactions for a best-in-class UX. See Gas abstraction

You can get your paymaster API key by contacting the AVNU team. The paymaster doc is here.

The paymasterParams is optional. If you pass it to the init function, every transactions will be executed through your paymaster configuration.

5. Request a connection

If the user is not connected, call the requestConnection() method to open the wallet and ask the user to approve the connection. At the same time, you can ask user for token approvals:

const handleConnect = async () => {
      try {
         const response =  await argentWebWallet.requestConnection({
            callbackData: "custom_callback_data",
            approvalRequests: [ // array of tokens
               {
                  tokenAddress: "0x049D36570D4e46f48e99674bd3fcc84644DdD6b96F7C741B1562B82f9e004dC7",
                  amount: BigInt("100000000000000000").toString(),
                  // Your dapp contract
                  spender: "0x7e00d496e324876bbc8531f2d9a82bf154d1a04a50218ee74cdd372f75a551a",
               },
            ],
         });		 
         const { account: sessionAccount } = response
         // rest of your connection logic
      } catch (err) {
         console.error(err);
      }
   };

The wallet will redirect back to your app and the account will be available from the connect() method.

6. Check connection status

You can check if the user is connected at any time using the isConnected() method:

const isConnected = argentWebWallet.isConnected();

7. Connect to the wallet

Call the connect() method when your app loads to check if the user is already connected. It is also used to fetch the account object. It is an extended starknet.js account object.

For instance, you could wrap this in a useEffect hook.

 useEffect(() => {
      argentWebWallet
        .connect() // call connect as soon as the app is loaded
        .then((res) => {
								
           if (!res) {
              console.log("Not connected");
              return;
           }

           console.log("Connected to Argent Web Wallet", res);
           const { account, callbackData, approvalTransactionHash } = res; // extract useful objects

           if (account.getSessionStatus() !== "VALID") {
              console.log("Session is not valid");
              return;
           }

           setAccount(account);
           console.log("Callback data", callbackData); // -- custom_callback_string
           console.log("Approval transaction hash", approvalTransactionHash); // -- custom_callback_string
        })
        .catch((err) => {
           console.error("Failed to connect to Web Wallet", err);
        });
   }, []);

8. Interact with Starknet using the account

You can interact with your contracts using starknet.js. For instance, you could do this:

const call = {
   contractAddress: "contract_address",
   entrypoint: "do_something",
   calldata: ["0x1"],
};

const { resourceBounds: estimatedResourceBounds } = await account.estimateInvokeFee(call, {
   version: "0x3",
});

const resourceBounds = { // configure fees
   ...estimatedResourceBounds,
   l1_gas: {
      ...estimatedResourceBounds.l1_gas,
      max_amount: "0x28",
   },
};

const { transaction_hash } = await account.execute(call, {
   version: "0x3",
   resourceBounds,
});

// Wait for transaction to be mined
await account.waitForTransaction(transaction_hash);

9. Check account session status

const sessionStatus = account.getSessionStatus();
// "VALID" | "EXPIRED" | "INVALID_SCOPE" | "INVALID_SIGNATURE"

10. Request approval

It is possible to ask to user to sign new approval transactions with requestApprovals().

async function handleApproval() {
    try {
      const res = await argentWebWallet.requestApprovals(
        [
          {
            tokenAddress: '0x049D36570D4e46f48e99674bd3fcc84644DdD6b96F7C741B1562B82f9e004dC7',
            amount: BigInt(1000000000000000000).toString(),
            spender: 'spender_address',
          }
        ],
      );
    } catch (error) {
      console.error('Approval failed:', error);
    }
  }

11. Clear session

Calling clearSession removes the session object from local storage. It is mostly used for debugging. The session would still be valid on-chain. In terms of UX, this pretty much looks like a disconnect feature.

We could imagine doing something like this:

const handleClearSessionButton = async () => {
    await argentWebWallet.clearSession();
    setAccount(undefined);
  };

---

List of useful ressources:

• npm package

• Invisible SDK tutorial