Интеграция с Biconomy (gasless)

Интеграция с Biconomy (gasless)

Пользователь нажимает «Mint» в вашем dApp — и видит MetaMask с запросом 0.003 ETH на газ. У него нет ETH, только NFT и USDC. Конверсия падает. Это не гипотетический сценарий: именно это убивает onboarding в большинстве Web3 приложений для массовой аудитории. Biconomy решает это через аккаунт-абстракцию.

Что такое Biconomy и как это работает

Biconomy — это реализация ERC-4337 (Account Abstraction) с собственной инфраструктурой: bundler, Paymaster, и Smart Account контракты. Пользователь не подписывает Ethereum транзакцию — он подписывает UserOperation (структурированный объект), bundler упаковывает несколько UserOperation в одну транзакцию и отправляет в mempool. Paymaster оплачивает газ.

Для разработчика это означает: backend или Paymaster-контракт платит за газ вместо пользователя, пользователь только подписывает intent.

Три ключевых компонента интеграции

Smart Account

Smart Account — это смарт-контракт, который является кошельком пользователя. В отличие от EOA, он может:

• Объединять несколько вызовов в одну транзакцию (batch)
• Поддерживать сессионные ключи (пользователь подписывает один раз, следующие N транзакций — без подписи)
• Иметь логику восстановления аккаунта
• Верифицировать подписи через кастомную логику (WebAuthn, passkey)

Biconomy предоставляет Modular Smart Account (v3), который совместим со стандартом ERC-7579 (модульные аккаунты). Деплой Smart Account для нового пользователя происходит автоматически при первом использовании через counterfactual deployment — контракт деплоится только при первой транзакции, а адрес вычисляется детерминированно заранее.

Paymaster

Paymaster — это контракт, который берёт на себя оплату газа. Biconomy предоставляет Sponsorship Paymaster (спонсируемые транзакции) и Token Paymaster (пользователь платит токенами вместо ETH).

Для Sponsorship Paymaster нужно:

1. Зарегистрировать проект в Biconomy Dashboard
2. Пополнить баланс MATIC/ETH для покрытия газа
3. Настроить whitelist контрактов и функций, которые спонсируются

Token Paymaster позволяет пользователю платить USDC, DAI, или любым ERC-20, поддерживаемым Paymaster. Конвертация в нативный токен для оплаты газа происходит внутри UserOperation.

Bundler

Bundler — это нода, которая принимает UserOperation от пользователей, валидирует их, упаковывает в batch и отправляет в сеть. Biconomy предоставляет hosted bundler через API. Для production важен выбор bundler по следующим параметрам:

• Latency (время от UserOperation до включения в транзакцию)
• Поддерживаемые чейны
• Rate limits и надёжность

Интеграция в dApp

Стек: @biconomy/sdk v4, viem, wagmi.

import { createSmartAccountClient } from "@biconomy/sdk";
import { createWalletClient, custom } from "viem";
import { polygon } from "viem/chains";

// Создаём Smart Account для пользователя
const walletClient = createWalletClient({
  chain: polygon,
  transport: custom(window.ethereum),
});

const smartAccount = await createSmartAccountClient({
  signer: walletClient,
  bundlerUrl: "https://bundler.biconomy.io/api/v2/137/nJPK7B3ru...",
  paymasterUrl: "https://paymaster.biconomy.io/api/v1/137/Tpk8nuCU...",
  paymasterTokens: [{ address: USDC_ADDRESS, decimal: 6, symbol: "USDC" }],
});

// Batch транзакция: approve + deposit за одну подпись
const txs = [
  { to: TOKEN_ADDRESS, data: approveCalldata },
  { to: PROTOCOL_ADDRESS, data: depositCalldata },
];

const userOpResponse = await smartAccount.sendTransaction(txs, {
  paymasterServiceData: { mode: PaymasterMode.SPONSORED },
});

const { transactionHash } = await userOpResponse.waitForTxHash();

Сессионные ключи

Сессионные ключи — одна из наиболее мощных возможностей Smart Account. Пользователь подписывает политику один раз: «разрешить адресу X вызывать функцию Y контракта Z с суммой не более N токенов в течение 24 часов». После этого сессионный ключ выполняет транзакции без участия пользователя — идеально для игр, автоматических стратегий, подписок.

const sessionModule = await createSessionKeyManagerModule({
  moduleAddress: SESSION_KEY_MANAGER_MODULE_ADDRESS,
  smartAccountAddress: smartAccount.accountAddress,
});

// Создаём сессию с ограничениями
const sessionData = await createSession(
  smartAccount,
  [{ sessionValidationModule: ERC20_SESSION_VALIDATION_MODULE, sessionKeyData }],
  null, // хранение в памяти или IPFS
  { paymasterServiceData: { mode: PaymasterMode.SPONSORED } }
);

Поддерживаемые сети

Типичные проблемы при интеграции

UserOperation reverts без понятной ошибки. Biconomy bundler валидирует UserOperation перед отправкой, но ошибки из calldata (например, revert в целевом контракте) возвращаются в hex без decode. Используем ethers.utils.parseError() или cast для decode revert reason.

Несовместимость контракта с Smart Account. Некоторые контракты проверяют msg.sender == tx.origin для защиты от контрактных вызовов. Smart Account — это контракт, поэтому tx.origin != msg.sender всегда. Такие проверки блокируют gasless транзакции. Нужно либо убирать проверку в контракте, либо использовать EntryPoint как trusted forwarder.

Counterfactual адрес не совпадает с ожидаемым. Smart Account адрес зависит от версии фабрики, salt, и signerAddress. При смене сети или версии SDK адрес может измениться. Всегда используем smartAccount.getAccountAddress() как единственный источник правды.

Интеграция базового gasless flow — 1-3 рабочих дня. Сессионные ключи и кастомные политики Paymaster — до 5 дней. Стоимость рассчитывается индивидуально.