Skip to content

refactor(paymaster): paymaster component as a tower layer#195

Open
kariy wants to merge 2 commits intomainfrom
refactor/paymaster
Open

refactor(paymaster): paymaster component as a tower layer#195
kariy wants to merge 2 commits intomainfrom
refactor/paymaster

Conversation

@kariy
Copy link
Member

@kariy kariy commented Jul 22, 2025

Instead of having Cartridge paymaster and VRF management strongly linked to Katana node/rpc, this PR implements paymaster/vrf as a tower layer of the Katana RPC server (i.e as a an optional middleware).

This tower layer is injected in the Katana RPC server when the cartridge feature is enabled.

The layer handles 2 enpoints:

  • starknet_estimateFee
  • cartridge_addExecuteOutsideTransaction

The global mechanism is almost the same for estimateFee and addExecuteOutsideTransaction. Each time one this endpoint is called, we check if:

  • the VRF provider is already deployed. if not, we deploy it,
  • the calling controller account is already deployed. If not, we deploy it,
  • an input transaction contains a VRF call request_random as first call. If yes, we just transform the call list to [VRF submit_random call, original calls, VRF assert_consumed call].

But there are some specificities to clarify/confirm:

  • when Katana is launched with -dev --dev.no-fee, starknet_estimateFee still returns a non-zero fee estimation. So, when we want to deploy/upgrade the controller account, the Cartridge controller UI shows a message telling the user to add funds to its controller account. But the user should be able to upgrade without any fee. To patch that, at the moment, the paymaster layer uses a build_no_fee_response() function to return zero fee.
    => this point should be clarify.

  • when cartridge_addExecuteOutsideTransaction() is called, a signature built in the Cartridge controller UI is provided. In the normal flow (without the paymaster layer), this outside_execution + signature input data is converted into an invoke transaction execute_from_outside_vX where the calldata are just the serialized outside_execution joined with the serialized signature.
    In the paymaster layer, in case of VRF request_random call, we have to modify the outside_execution to inject 2 VRF calls (submit_random and assert_consumed) and so, we should generate another signature. The thing is that the signature format is not just a classic [r, s, v] signature. So, at the end, to avoid having to generate a new signature, I decided to return an empty signature and use the outside_execution as a way to the call vector to use to build the final invoke tx. So, in cartridge/rpc, you will see a specific process when the signature is empty.

To validate this PR, I create a tiny web app with the Cartridge controller:

  • declare/deploy the contract (from contracts folder, using scripts),
  • run the web app using pnpm run dev,
  • connect the cartridge controller,
  • upgrade your controller account,
  • use dice buttons.

@kariy kariy added this to the 1.7.0 milestone Sep 9, 2025
@kariy kariy modified the milestones: 1.7.0, 1.8.0 Sep 23, 2025
@remybar remybar force-pushed the refactor/paymaster branch 2 times, most recently from 944d536 to 0881ed6 Compare November 18, 2025 04:00
@remybar remybar force-pushed the refactor/paymaster branch from 54b5ee7 to 53bcec8 Compare December 5, 2025 18:27
@kariy kariy force-pushed the refactor/paymaster branch from ecbaf09 to 37c9a36 Compare December 18, 2025 08:12
@kariy kariy force-pushed the main branch 2 times, most recently from e3bd68b to e897bbb Compare December 30, 2025 17:28
@remybar remybar force-pushed the refactor/paymaster branch from 37c9a36 to 0aa1f33 Compare January 4, 2026 18:10
@remybar remybar force-pushed the refactor/paymaster branch 2 times, most recently from 8dbe0d5 to 8ba4471 Compare February 10, 2026 22:07
@remybar remybar marked this pull request as ready for review February 13, 2026 03:31
@remybar remybar requested a review from glihm February 13, 2026 03:32
@remybar
Copy link
Collaborator

remybar commented Feb 13, 2026

Hey @kariy @glihm !

I rebased this PR + fixed tests / clippy. I updated the PR description to give some details about the implementation and some points to check/clarify/confirm.

I also squashed commits to ease review and rebase 😅 I kept the first commit (the tower layer setup from @kariy) and the second commit (what I added).

I just see that a new rebase is needed. I will try to do it tomorrow...

@kariy
Copy link
Member Author

kariy commented Feb 13, 2026

@remybar Sorry I forgot to mention this but since #399 the paymaster and VRF are no longer integrated directly in the Cartridge RPC - they are running as external services. But this PR is still valid.

The conflicts are pretty complex I can rebase it for you.

@remybar
Copy link
Collaborator

remybar commented Feb 13, 2026

The conflicts are pretty complex I can rebase it for you.

Hey @kariy, yes, I just discovered this refactor this morning. Yes, it will be more efficient if you can rebase it 👍

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants