Setup

Installation

Start by getting the Paymaster CLI:

git clone https://github.com/avnu-labs/paymaster
cd paymaster

Launch setup

In order to run the paymaster, you need to deploy several contracts, but no worries all is done in one cmd as described bellow.

--chain-id is either "sepolia" or "mainnet"
--master-address is the account which is gonna deploy and become the owner of the forwarder
--master-pk is the private key of the master-address account
--rpc-url is the url of a Starknet node (optional)
--rpc-timeout is the connection timeout in SEC to a Starknet node (optional - default 1)
--rpc-port is the Starknet node connecting port (optional - default: 12777)
--num-relayers is the number of initial relayers (optional - default: 2)
--fund is the initial amount of STRK to transfer to the gas tank (optional - default: 10)
--estimate-account-fund is the initial amount of STRK to transfer to the estimate account (optional - default: 10)
--max-check-status-attempts is the max attemps to check for a transaction validation on a Starknet node (optional - default: 5)
--min-swap-sell-amount is the minimum value in USD you want to swap when rebalancing (optional - default: 1)
--max-fee-multiplier is the multiplier between the fee calculated & the max fee user accept to pay (optional - default: 3)
--fee-overhead is the overhead you take for each transaction as security (optional - default: 0.1)
--min-relayer-balance is the minimum balance of STRK needed in a relayer before he's considered disabled (optional - default: 1)
--rebalancing-check-interval is the interval in SEC between 2 attempts of rebalancing (optional - default: 3600 * 24) see rebalancing
--rebalancing-trigger-balance is the trigger point of the rebalancing if any of the relayers reach this balance (optional - default: 8) see rebalancing
--swap-slippage is the maximum acceptable slippage for a swap (optional - default: 0.01)
--swap-interval is the interval in SEC between 2 attempts of swapping supported_tokens (optional - default: 3600)
--max-price-impact is the maximum acceptable price impact for a swap (optional - default: 0.05)
--verbosity is either "info" or "debug" (optional - default: info)
--profile is the complete path of the profile you're setting up (optional - default: default.json)

cargo run --bin paymaster-cli setup --chain-id=CHAIN_ID --master-address=0xdead --master-pk=0xbeef --profile=path/to/my-profile.json

Output example

Starting Paymaster setup...

Using chain-id: SN_SEPOLIA

Using RPC URL: https://starknet-sepolia.public.blastapi.io

Nbr of relayers: 2

Minimum relayer balance: 1 STRK

Rebalancing trigger balance: 8 STRK

Fund estimate account with: 10 STRK

Fund gas tank with: 1 STRK(reserve) + 20 STRK(fund)

Total amount to fund paymaster: 31 STRK

Profile path: path/to/my-profile.json

Do you want to proceed with the deployment? This will transfer 31 STRK tokens to your relayers and estimate account. (y/N): y

Proceeding with deployment...

get_transaction_status; hash=0x...

get_transaction_status; hash=0x...

Transaction succeeded: 0x...

Paymaster contracts are deployed, tx = 0x...

Profile not found, created new configuration profile at: path/to/my-profile.json

Configuration file is updated, see path/to/my-profile.json

📘
Initial funding of the relayers
A part of the paymaster setup consist of relayers deployment & funding to be able to run transactions, therefore you can choose how many relayers you want to deploy and the initial amount of STRK to send to each of them.
Additionally, an estimate-account is deployed to be able to run tx estimations, and also have to be funded.
The total amount of STRK = num-relayers * fund + estimate-account-default-funding

Run your instance

You now have all the contract architecture needed to manage Gasless transactions, congrats 🥳

Let's continue by running your instance & monitor it!

❗️
Keep your profile.json in a safe place
If you look at /profiles/my-profile.json you'll see all the configuration of your paymaster, including sensitive data like the relayers private keys.
Good to know: As the forwarder owner is "master-address"(and master-pk is never saved), the risk of leaking your profile is limited to your relayers fund to be drained.