permissionless.js

The permissionless library provides utility functions organized into five main functional categories:

1. Nonce Utils: Handles 2D nonce encoding and decoding (encodeNonce, decodeNonce).
2. UserOperation Utils: Functions for UserOp packing and gas computation (getPackedUserOperation, getRequiredPrefund, deepHexlify, transactionReceiptStatus).
3. ERC-7579 Utils: Module encoding and decoding for ERC-7579 (encode7579Calls, decode7579Calls, encodeInstallModule, encodeUninstallModule).
4. ERC-20 Utils: State overrides for gas estimation (erc20AllowanceOverride, erc20BalanceOverride).
5. Account Utils: Helpers for smart account management (isSmartAccountDeployed, toOwner, getAddressFromInitCodeOrPaymasterAndData).

permissionless.js is a TypeScript library built on top of viem for managing ERC-4337 smart accounts. Key capabilities include:

• Smart Account Support: High-level API for popular implementations like Safe, Kernel, and Biconomy.
• Bundler Support: Full support for all ERC-4337 bundler RPC methods.
• Gas Sponsorship: Support for paymaster actions to sponsor gas fees.
• User Operation Utilities: Low-level utility functions for handling User Operations.
• Extensibility: Modular design allowing custom smart accounts, bundlers, paymasters, and signers.

permissionless is a TypeScript SDK built on viem designed for working with ERC-4337 Account Abstraction.

Key capabilities include:

• Smart Account Support: Support for 12 different smart account implementations (including Safe, Kernel, Biconomy, and more).
• Bundler & Paymaster Integration: Support for multiple bundler providers and paymaster interactions.
• Advanced Standards: Support for ERC-7579 modular accounts and EIP-7702 delegation.
• Extensible Actions: A system of 'Actions' that allow for both standalone utility usage and decorated client usage (e.g., sendTransaction, signMessage).

The @permissionless/wagmi library is a TypeScript wrapper built on top of permissionless.js and wagmi. It is designed to allow developers to support EIP-5792 features (such as those used by Coinbase Smart Wallet) with minimal complexity.

Key features include:

• ERC-7677 Paymaster service: Simplifies interaction with external smart accounts that offer paymaster support.
• Transaction Batching: Enables sending multiple transactions from an external smart account easily.
• Wagmi Integration: Maintains the same developer experience and style as the standard wagmi library.

A smart account is a contract that validates UserOperations. Unlike EOAs, they can implement logic like multi-sig, session keys, or social recovery.

In permissionless, you create a SmartAccount using factory functions like toSimpleSmartAccount(), toSafeSmartAccount(), toKernelSmartAccount(), etc. Each returned SmartAccount provides the following methods:

• getAddress(): Returns the counterfactual address (works before deployment).
• encodeCalls(calls): Encodes calls into account-specific calldata.
• decodeCalls(data): Decodes calldata back to calls.
• getNonce(): Gets current nonce from EntryPoint.
• getStubSignature(): Gets a dummy signature for gas estimation.
• sign(hash): Signs a hash.
• signMessage(message): Signs an EIP-191 message.
• signTypedData(typedData): Signs EIP-712 typed data.
• signUserOperation(userOperation): Signs a UserOperation.

ERC-4337 utilizes a 2D nonce system composed of a key (192 bits) and a sequence (64 bits).

• Key: Identifies the 'nonce lane'. Using different keys allows for parallel nonce lanes, meaning multiple UserOperations can be in-flight simultaneously without blocking one another.
• Sequence: A value that increments per operation within a specific lane.

The BiconomySmartAccount uses an ECDSA validation module and supports EntryPoint 0.6.

Note: This implementation is deprecated. For new integrations, use NexusSmartAccount instead.

The Light Account implementation includes the following characteristics:

• ERC-1271: Full support for signMessage and signTypedData via an EIP-1271 wrapper.
• ERC-7579: Not supported.
• Signing: Uses standard ECDSA signing.

The SafeVersion determines which EntryPoint version is compatible with your account. You must match them as follows:

• 1.4.1: Use this for EntryPoint 0.6.
• 1.5.0: Use this for EntryPoint 0.7 (Recommended).

The project uses conditional exports in package.json to ensure compatibility across different module systems. When consuming a package, the environment will resolve to the appropriate format:

• types: Used by TypeScript to resolve .d.ts files from the _types/ directory.
• import: Used by ESM bundlers and Node.js (with "type": "module") to resolve files from the _esm/ directory.
• default: Used by CommonJS require() calls to resolve files from the _cjs/ directory.

Example Export Map

{
  "exports": {
    ".": {
      "types": "./_types/index.d.ts",
      "import": "./_esm/index.js",
      "default": "./_cjs/index.js"
    }
  }
}

A factory deploys smart account contracts on first use. The first UserOperation from a new account includes factory data that triggers deployment.

In permissionless:

• Each to*SmartAccount() factory configures the factory internally.
• The getFactoryArgs() method returns { factory: Address, factoryData: Hex } for the first UserOp. After deployment, it returns undefined.
• You can pass a custom factoryAddress to the factory configuration.