Every time your UP does something on a blockchain, for example sending money, a small fee is paid: the
gas. Normally whoever signs pays it, so the controller would need to keep a little money on every
network. With this page it no longer does.
The cassa is the wallet that pays. It puts money in a piggy bank, the paymaster, and decides
which UPs may use it.
The UP's controlleronly signs, the way you sign a form. It pays nothing.
The site relayer takes the signed form to the blockchain, advances the fee and gets it back from the
piggy bank.
To prepare once:
the cassa creates the piggy bank, fills it and sets the most it may pay for each operation (section 3);
the cassa puts the UP on the list of those who may use it (section 4);
the controller authorises the UP to use this system (section 4). It is the only time the controller pays a
little gas.
Then, every time: the controller signs (A) and the site relayer sends (B). The piggy bank pays the fee;
the UP pays only what it sends.
📘 Step-by-step guide: who does what, several MetaMask accounts, order of the
steps
Who does what
Cassa, the paymaster owner: publishes, funds, sets the cap and withdraws (section 3), puts UPs on
the allowlist or removes them (section 4). All of these are done with the cassa active in MetaMask.
The UP's controller: sets up the UP, once per chain (section 4), and signs every operation (button
A). The setup costs a little gas; operations do not.
Site relayer: sends the signed operation (button B). No MetaMask account is needed.
UP extension (optional): only reads the UP address. It signs nothing here.
The MetaMask accounts
Always connect the cassa first. Make the cassa active in MetaMask, then press Connect
MetaMask. In the MetaMask window you can tick the controller too: both stay connected.
The Owner field in section 3 must always be the cassa. If the site runs a relayer, the page
fills it in and remembers it. If you see another address, correct it: otherwise the page computes another
paymaster, which does not exist.
The page always uses the account active in MetaMask, and only that one. To switch, open MetaMask
and pick the other account from the menu at the top; if MetaMask says it is not connected to this site, use
its Connect button. Then check the MetaMask row in section 1; if it does not update, press
Connect MetaMask again. An operation already signed is kept.
UP extension and MetaMask active together is normal: they do two different jobs.
Every time you open or reload the page
Tick I have read and accept below: without it the buttons stay grey.
Section 1: choose the network and enter the UP address.
Section 2: the check runs by itself and says what is missing and where to do it.
Section 3: check that the Owner is the cassa.
Once per chain, with the cassa active
Publish the paymaster, if missing.
Fund it.
Set the cap per operation.
Section 4: if Extension4337 shows not published, press Publish Extension4337 on this
network. Here the cassa only pays the gas: the extension is a public contract, the same for everyone,
and whoever publishes it gets no rights over any UP. Once per network.
Each button opens MetaMask to confirm a transaction of the cassa. The paymaster and Extension4337 are
published through the standard contract factory 0x4e59b448…956C: MetaMask may show it with no
name or odd characters, that is normal.
For each UP
Enter the UP address in section 1.
With the cassa active, section 4, Paymaster allowlist: press Add the UP to the
allowlist. After a few seconds MetaMask opens and asks you to confirm a transaction: check that
the account is the cassa and confirm. It costs very little gas, paid by the cassa. After the confirmation
the box says The UP is on the allowlist.
Switch to the UP's controller in MetaMask (the genesis key or the backup, never the cassa)
and check section 1: the Active account's permissions row in section 4 must show the permissions, not
"not a controller".
Section 4, Setup: Prepare and simulate, read the plan, then Sign and send and confirm
in MetaMask. One transaction, with a little gas paid by the controller (its account needs a little of the
network's currency); the page verifies the result. The signing controller receives the 4337 permission: to
sign operations with the other controller too, repeat the setup with it active.
The UP must hold on this network the money it wants to send: the paymaster pays the gas, not the amount.
Every operation, with the controller active
A · Prepare and sign: compare the fingerprint in MetaMask with the page's, then sign. No gas.
B · Send: done by the site relayer. No account switch, no signature.
While you wait
After each click a box at the bottom shows the status. Before MetaMask opens the page reads the data and
simulates: it can take a few seconds. Do not click again.
When you switch account or network in MetaMask, the box Updating the data appears too: the page
reads everything again and the buttons stay grey for a few seconds. Wait until it goes away.
If MetaMask does not appear, open the extension: the request may be waiting there.
Checking the configuration
Section 2, Check the configuration: read-only, no signature, no wallet. It needs only the network,
the UP address and the paymaster owner. Each item shows ✅, ⚠️ or ❌; the most important one is
EntryPoint's permissions = 0x000500. Run it after any change to the UP and on every network. The
server also repeats it every hour and emails the operator if something changes.
Going back
Section 4, Turning 4337 off on this UP: one controller transaction restores the UP as it was.
Section 4, Remove from the allowlist, with the cassa.
⚠️ Read before using this page
Experimental tool, not audited. The paymaster and LUKSO's Extension4337 have not been
reviewed by third parties. Use small amounts.
It changes the UP's configuration on this chain: the EntryPoint becomes a controller with call and
value-transfer permissions. It only executes operations signed by a controller with the 4337 permission,
within the signer's own permissions.
The paymaster deposit is spent by every operation of allowlisted UPs: add only UPs you trust and keep
the deposit low.
No warranty. Software "as is" (MIT licence): use it at your own risk. No affiliation with LUKSO or
anyone else.
This page never asks for private keys: you sign everything in MetaMask.
1 · Network, MetaMask and UP
Each section uses the account active in MetaMask:
the cassa for the paymaster and the allowlist, the UP's controller for the setup and the signature. Connect the
cassa first: see the guide in section 0.
Not checked yet.
2 · Configuration check
Read-only: no signature, no gas. It needs only the network and the UP
address (section 1) and, for the paymaster, the owner (section 3); MetaMask is not needed. It checks that the UP,
the extension, the EntryPoint, the controllers, the paymaster and the site relayer are set up as expected. The key
point: the EntryPoint must have exactly the permissions 0x000500 (call and send value, no change of
data or permissions). Run it again after any change to the UP and on every network.
No check run yet.
4 · The UP
UP setup · with the controller
Two steps, with different accounts: 1 · Publish
Extension4337, only if the box below says not published: once per network, then it serves every UP.
Any account can sign it, for example the cassa: it only pays the gas and gets no rights over any UP,
because the contract is public and the same for everyone. In MetaMask the transaction goes to the standard
contract factory 0x4e59b448…956C, which may show no name or odd characters: that is normal. 2 ·
Set up the UP with the UP's controller active in MetaMask (the genesis key or the backup, never
the cassa): one atomic Key Manager transaction, with a little gas paid by the controller; if any part fails,
nothing changes. The signing controller receives the 4337 permission. Before signing you see the list of
operations and the simulation.
Not checked yet.
No operation prepared.
Turning 4337 off on this UP
Undoes the setup with one transaction of the controller: it
removes the extension for validateUserOp, the EntryPoint's permissions and its place in the
controllers list, and the 4337 permission of the active account. Afterwards no operation can go through the
EntryPoint on this UP. The other permissions stay identical. It can be set up again at any time.
