zkSync Era Account Abstraction and Paymasters: Developer Guide 2026

Account abstraction means an account is controlled by programmable code rather than only by a single private key signing a transaction. On zkSync Era, a ZK rollup that settles to Ethereum, this idea is built into the protocol itself. The network does not treat a regular key-based wallet as a special case. Every account is a smart contract account, so features that usually need extra tooling can be handled at the base layer.

For users, the practical result is flexibility. A wallet can pay fees in a token other than the native gas token, can have a sponsor cover fees, and can use custom signature rules. For developers, the protocol gives a consistent model: you write the validation logic for an account or a paymaster, and the network calls that logic in a defined order.

This is different from building account abstraction on a chain where it arrives only through an add-on standard. On zkSync Era, the account model is part of how transactions are processed, so the rules are enforced by the protocol as well as by your contracts.

If you are new to the topic, think of two roles. The account decides whether a transaction is authorised. The paymaster decides whether it will pay the fee. Keeping those roles separate makes the rest of the design easier to reason about.

On many networks, an externally owned account, or EOA, is a plain key pair with no code. zkSync Era changes that model. Every account is a contract, and a key-based wallet is simply a contract account that checks a signature from a known key. This means a standard wallet and a custom smart account share the same protocol path.

The benefit is that features do not need a separate account type. A paymaster can sponsor a transaction from a basic wallet, and a custom account can add its own rules without the user moving to a new address.

Several differences matter in practice:

• Validation is programmable. The account contract decides what counts as a valid transaction.
• Fee payment can be delegated. The transaction can name a paymaster that covers the fee.
• Nonce handling and signature schemes can vary by account design.
• Contract addresses and deployment behaviour may differ from what you expect on other EVM chains.

Developers should not assume that code written for an Ethereum EOA will behave the same way here. Test how your app reads account state, how it signs messages and how it handles a transaction that is validated but not executed. Small differences in these details often cause the bugs that appear after launch.

A paymaster is a contract that can pay transaction fees for a user. It is useful when you want users to pay no gas, or want them to pay in a token that your app already uses. Common patterns include:

• Full sponsorship, where the app or a sponsor covers every fee for eligible users.
• Token-based payment, where the user pays a fee in an accepted token and the paymaster handles the native gas.
• Rule-based sponsorship, where the paymaster only pays for specific contracts, actions or allow-listed accounts.

The paymaster needs funds in the native token to cover the fees it has agreed to pay. If it runs out, transactions that depend on it will fail. Plan a top-up process and set alerts on the balance. Limits on how much one account can use also protect the sponsor from abuse.

From the user side, the experience should be simple: they sign an action and the app handles the fee path. From the developer side, the design work is deciding who pays, under what conditions, and how the paymaster verifies that a request is allowed. Write those rules down before writing any code, because they become the security model for the whole app.

Each transaction on zkSync Era goes through a sequence of checks. Knowing the order helps you find where a failure happens. In broad terms, the network first asks the account contract whether the transaction is valid. Then it asks the paymaster, if one is named, whether it agrees to pay. Only after both checks pass does the transaction execute.

The steps are:

1. The network reads the transaction and calls the account validation logic.
2. If a paymaster is named, the network calls its validation logic.
3. The fee is paid according to the rules of the account or paymaster.
4. The transaction executes its intended actions.
5. Any post-transaction logic in the paymaster runs, if the design includes it.

If validation fails at step one or two, the transaction does not execute. This is important for user experience, because a rejected transaction should not leave the user charged for work they did not get. Design your error messages so that a developer can tell which check rejected the transaction.

Because validation runs before execution, your validation code should be simple and must not depend on state that can change between checks in unexpected ways. Keep it deterministic and read only what it needs.

Building a custom account is an advanced task. Treat it as a series of steps and avoid skipping the testing stage.

1. Define what the account must check. Decide whether it verifies a single key, multiple signers, a session key or a social recovery path.
2. Start from the official example contracts and interface definitions published for zkSync Era. Do not write validation logic from scratch if a reviewed example already matches your design.
3. Implement validation so that it returns the correct result for valid and invalid signatures. Confirm that invalid transactions are rejected.
4. Implement execution, making sure the account only performs actions its owner has authorised.
5. Add access control for administrative functions, such as changing signers or upgrading the account.
6. Write tests for each path, including replayed transactions, wrong signatures and paymaster-related requests.
7. Deploy to a testnet and run real transactions from a wallet your team controls.
8. Commission a security audit before you move meaningful funds into the account.

Keep the account as small as the product requires. Every extra feature is more code that must be reviewed. Document who can change the signer list, what happens if a key is lost, and how users recover access. Those answers should exist before launch, not after an incident.

A paymaster contract has two main jobs. It must decide whether to pay for a transaction, and it must collect payment or enforce its rules. Two patterns are common in zkSync Era examples.

The first is an approval-based flow. The user approves a token spend to the paymaster, and the paymaster takes an agreed amount of that token to cover the fee. This pattern is easy to understand, but it creates a permission that must be limited. Users should approve only the amount needed, and your app should show the amount clearly.

The second is a signature-based flow. The app's backend signs an approval for a specific transaction or user, and the paymaster checks that signature on-chain before paying. This allows flexible rules, such as sponsoring one action or enforcing an off-chain policy. The risk is in the signer: if the signing key is exposed, anyone with that key can approve sponsorship.

Whichever pattern you choose:

• Keep the signing key in a secure key management system, not in front-end code.
• Bind each approval to a specific transaction, user and expiry time, so signatures cannot be reused.
• Cap the amount the paymaster will pay per user or per period.
• Log every sponsored transaction so you can detect abuse.

The example contracts are a starting point. Review them against your own rules before you adapt them.

Testing account abstraction code needs more care than testing a standard token contract, because the failure modes are more varied. A reliable test plan covers normal use and the cases where things go wrong.

Cover at least these scenarios:

• A valid transaction from the intended owner executes and the fee is paid as designed.
• A transaction with a wrong or missing signature is rejected before execution.
• A transaction that names a paymaster with insufficient balance fails cleanly.
• A sponsored transaction is rejected when it breaks the paymaster's rules, such as a non-allowed contract or an expired approval.
• A replayed approval cannot be used twice.
• A token-based fee path behaves correctly when the user has too little of the accepted token.

Run these on a zkSync Era testnet first, then repeat a smaller set on mainnet after a staged launch. Use separate keys and funds for testing, and never reuse a production signing key in a test environment.

Record the gas usage and fee amounts you observe, but do not treat them as permanent. Network fees and token prices change, so set alerts that compare live results with your test assumptions. A test suite is most useful when it is run again after every contract upgrade.

Most problems with account abstraction fall into a few groups. Start by identifying which stage failed.

If a transaction is rejected immediately, check the account validation logic first. A wrong signature format, a nonce mismatch or a signer that is not registered will stop the transaction before any fee is taken. Compare the signed data with what the contract expects.

If the transaction is rejected only when a paymaster is named, check the paymaster's balance and its validation rules. An empty balance, an expired approval or a token allowance that is too low are common causes. A rule that blocks a particular contract or user will also produce this kind of failure.

If the transaction succeeds but charges an unexpected fee, check which token the fee was paid in and which contract paid it. Confirm the paymaster's token accounting and the amount your app displayed to the user.

When reporting an issue to a library or tool maintainer, include the network, contract addresses, the transaction hash from a block explorer, the exact error message and the version of the tool you used. Good reports speed up diagnosis. Do not post private keys, seed phrases or signed messages that could still be used.

Security is the main risk in this area. A paymaster that holds funds, and an account that holds assets, are targets. The advice below is defensive and applies to both users and developers.

For users:

• Read each approval request. Check which contract is asking, which token is involved and how much it can spend.
• Revoke token approvals you no longer need, using a reputable approval management tool or your wallet's settings.
• Be cautious of any link or message that asks you to sign something unexpected, even if it appears to come from a known app.
• Keep recovery information offline and never share it.

For developers:

• Get an independent security audit before holding user funds.
• Limit administrative powers with timelocks or multi-signature control where your design allows.
• Keep signing keys for paymaster approvals in a hardware-backed or managed key system, and rotate them if exposure is suspected.
• Monitor paymaster balances, unusual sponsorship volume and repeated failed validations.
• Publish an incident response plan that says who can pause sponsorship and how users will be told.

No design removes all risk. Account abstraction gives more control, which also means more ways to make a mistake. Keep the scope small and the rules explicit.

Tooling and the ecosystem change quickly, so check current options before choosing a stack. zkSync Era has public documentation, reference contracts and community examples, and several third-party developer tools exist for bridges, paymaster builders and SDKs. Evaluate any tool by reading its code and documentation, checking when it was last updated and confirming that it targets the current network version.

For data, use a block explorer for the network to verify transactions and contract state. For protocol-level integrations, read the documentation and changelogs for the specific tools you plan to use. Infrastructure providers and indexers can help you read on-chain events, but you should still verify important results against the chain itself.

If your app needs to interact with established DeFi protocols on the network, confirm which deployments exist and which chains they support, because support changes over time. The protocols listed alongside this guide are useful reference points for lending, decentralised exchange and cross-chain activity, but check each protocol's own documentation before assuming it is available on zkSync Era.

Finally, keep a short record of the versions you tested, the contract addresses you deployed and the date of your last review. That record helps your team respond quickly when the network or a dependency changes.