Add paymaster API SNIP #132

leo-starkware · 2025-02-05T09:38:04Z

This change is

sgc-code · 2025-02-05T10:17:01Z

SNIPS/snip_x.md

+From the point of view of the user, the critical juncture during a "full" interaction with a paymaster (i.e. one that involves calling method `buildTypedData` and then `execute`) is the inspection of the typed data returned to them by the `buildTypedData` endpoint. In case the user account is already deployed, the array of calls in this object SHOULD either
+1. Be exactly equal to the array of calls submitted by the user.
+2. The first call is a single `Transfer` call originating from the user account and calling the ERC-20 contract of the requested token, followed by the array of calls submitted by the user.


this can be slightly different is we use SNIP-9 revision 3

Added clarification in dcbcd07

sgc-code · 2025-02-05T10:22:32Z

assets/snip-x/paymaster_api.json

+            ],
+            "result": {
+                "name": "result",
+                "description": "The hash of the transaction broadcasted by the paymaster",


not sure if out of scope. But what happens if there's a gas spike and the transaction is stuck. The paymaster will need to replace it with a new transaction to avoid having a stuck relayer. In that case there will be a new tx hash...
Maybe there could be another function to get the latest tx?

Added in dcbcd07

sgc-code · 2025-02-06T09:01:06Z

assets/snip-x/paymaster_api.json

+            }
+        },
+        {
+            "name": "paymaster_trackingIdToLatestHash",


i'm thinking we might need to return a status as well. If the transaction is subsidized the paymaster can just update the tx hash (if they support this functionality). But when paying in a different token the paymaster can't just increase the gas price, the user needs to sign the data again to agree to the new fee. I think the paymaster should be able to indicate this situation here

In the flow where the user first asks the typed data, and the paymaster returns the typed data with a max fee (possibly with transfer call preprended), then I imagine that this max fee should have some leeway to allow for bumps in gas/tip - the redeposited amount should also account for this. Also, once a tx is sitting in the mempool and not rebumped, it's hard to say if it's still valid or it should be regarded as "failed" from the POV of the user, because it's failing to enter a block. Not sure that this logic should belong to the paymaster.

i see your point, but if the relayer tx is stuck. The paymaster will eventually replace the transaction with another transaction with the same (regular) nonce, but carrying a different outside execution. At this point the paymaster knows for sure that the tx is stuck forever

I get your point now. The status is actually a signal from the paymaster saying "i'm not dealing with this execution request anymore". Theoretically with nonce channels (or even without, just by dropping the relayer), the paymaster is not forced to make the tx permanently invalid by sending one with the same nonce, I agree it's good to signal that the paymaster is not trying anymore

Done in 74fbb7a

ArielElp

Reviewable status: 0 of 2 files reviewed, 14 unresolved discussions (waiting on @bbrandtom and @sgc-code)

assets/snip-x/paymaster_api.json line 157 at r3 (raw file):

                            "type": "object",
                            "properties": {
                                "max_amount": {

Rename to estimated_amount? this is confusing with the actual tx field IMO

assets/snip-x/paymaster_api.json line 281 at r3 (raw file):

                },
                {
                    "$ref": "#/components/errors/INVALID_REQUEST_PAYLOAD"

What is invalid in this context? In general the RPC errors should only be semantic, the structure is enforced by the specs themselves

assets/snip-x/paymaster_api.json line 284 at r3 (raw file):

                },
                {
                    "$ref": "#/components/errors/INVALID_SIGNATURE"

The paymaster service is expected to run a starknet_call to is_valid_signature with the message hash? If yes, can we make it explicit in the spec somewhere?

assets/snip-x/paymaster_api.json line 293 at r3 (raw file):

                },
                {
                    "$ref": "#/components/errors/TRANSACTION_EXECUTION_ERROR"

Is this specific to the execution of validate? If yes, let's rename to something like VALIDATE_EXECUTION_ERROR/VALIDATION_FAILED (generalizes invalid signature). Also, possible duplicated with INVALID_SIGNATURE

assets/snip-x/paymaster_api.json line 351 at r3 (raw file):

                    },
                    "required": [
                        "transaction_hash",

What should the transaction hash be in active/dropped?

assets/snip-x/paymaster_api.json line 425 at r3 (raw file):

                "$ref": "#/components/schemas/FELT",
                "description": "The transaction ID",
                "title": "Transaction hash"

Are the title and description fields wrong? IIUC this is meant for the paymaster backend to associate the request with a fresh tx hash, rather than be an actual Starknet tx hash

assets/snip-x/paymaster_api.json line 450 at r3 (raw file):

                    "types": {
                        "type": "object",
                        "additionalProperties": {

should be properties? same for the other typed data versions

assets/snip-x/paymaster_api.json line 457 at r3 (raw file):

                        }
                    },
                    "primaryType": {

Is it important to be consistent with SNIP12 here or can we keep snake case property names? if the latter, this is relevant to all the other versions as well

assets/snip-x/paymaster_api.json line 847 at r3 (raw file):

                    },
                    {
                        "title": "No fee",

How about a string enum with one value NO_FEE? I don't think spaces are allowed in property names

assets/snip-x/paymaster_api.json line 861 at r3 (raw file):

                    "Fee Amount": {
                        "title": "Fee amount",
                        "$ref": "#/components/schemas/u256_AS_FELTS"

Why does the spec need to know about Cairo's representation of uint26? (part of the broader discussion on should the paymaster spec use SNIP12 terminology)

assets/snip-x/paymaster_api.json line 987 at r3 (raw file):

                        "type": "integer",
                        "enum": [
                            0,

Why should we support Cairo0 here? They would in any case have to go through a dedicated flow to upgrade

leo-starkware

Reviewable status: 0 of 2 files reviewed, 12 unresolved discussions (waiting on @ArielElp, @bbrandtom, and @sgc-code)

assets/snip-x/paymaster_api.json line 281 at r3 (raw file):

Previously, ArielElp wrote…

What is invalid in this context? In general the RPC errors should only be semantic, the structure is enforced by the specs themselves

Removed

assets/snip-x/paymaster_api.json line 284 at r3 (raw file):

Previously, ArielElp wrote…

The paymaster service is expected to run a starknet_call to is_valid_signature with the message hash? If yes, can we make it explicit in the spec somewhere?

See reply to TRANSACTION_EXECUTION_ERROR comment below

assets/snip-x/paymaster_api.json line 293 at r3 (raw file):

Previously, ArielElp wrote…

Is this specific to the execution of validate? If yes, let's rename to something like VALIDATE_EXECUTION_ERROR/VALIDATION_FAILED (generalizes invalid signature). Also, possible duplicated with INVALID_SIGNATURE

The paymaster will simulate the tx before sending it, and this error corresponds to a reverted tx. The INVALID_SIGNATURE error should be a "sub-error" which corresponds to a revert specifically due to the invalid user signature (which happens in execute so I wouldn't call it VALIDATE_EXECUTION_ERROR/VALIDATION_FAILED). Maybe should rename TRANSACTION_EXECUTION_ERROR to SIMULATED_TRANSACTION_REVERTED?

assets/snip-x/paymaster_api.json line 351 at r3 (raw file):

Previously, ArielElp wrote…

What should the transaction hash be in active/dropped?

The hash of the most recent tx sent by the paymaster and corresponding to the ID

assets/snip-x/paymaster_api.json line 425 at r3 (raw file):

Previously, ArielElp wrote…

Are the title and description fields wrong? IIUC this is meant for the paymaster backend to associate the request with a fresh tx hash, rather than be an actual Starknet tx hash

Done

assets/snip-x/paymaster_api.json line 450 at r3 (raw file):

Previously, ArielElp wrote…

should be properties? same for the other typed data versions

Copied from the corresponding objects in the wallet <> Dapp RPC

assets/snip-x/paymaster_api.json line 987 at r3 (raw file):

Previously, ArielElp wrote…

Why should we support Cairo0 here? They would in any case have to go through a dedicated flow to upgrade

Done

ArielElp

Reviewable status: 0 of 2 files reviewed, 10 unresolved discussions (waiting on @bbrandtom, @leo-starkware, and @sgc-code)

assets/snip-x/paymaster_api.json line 351 at r3 (raw file):

Previously, leo-starkware wrote…

The hash of the most recent tx sent by the paymaster and corresponding to the ID

What if it was never sent, should it be optional? Also you should add what you wrote here to the description

assets/snip-x/paymaster_api.json line 450 at r3 (raw file):

Previously, leo-starkware wrote…

Copied from the corresponding objects in the wallet <> Dapp RPC

Can you change to type array and items, it's also "wrong" there IMO>

assets/snip-x/paymaster_api.json line 987 at r3 (raw file):

Previously, leo-starkware wrote…

Done

Can we remove the entire field then, and assume that calldata is supposed to be encoded for Cairo1 accounts?

assets/snip-x/paymaster_api.json line 1015 at r4 (raw file):

                "message": "An error occurred (CLASS_HASH_NOT_SUPPORTED)"
            },
            "TRANSACTION_EXECUTION_ERROR": {

This was changed in the latest RPC to have a recursive structure, can you take it from the v0.8.0 branch?

leo-starkware

Reviewable status: 0 of 2 files reviewed, 10 unresolved discussions (waiting on @ArielElp, @bbrandtom, and @sgc-code)

assets/snip-x/paymaster_api.json line 351 at r3 (raw file):

Previously, ArielElp wrote…

What if it was never sent, should it be optional? Also you should add what you wrote here to the description

A tracking ID comes into existence after a successful response from the execute endpoint, which is also required to return a tx hash (= the first tx hash to be associated with the tracking ID). Will add more details to the description

leo-starkware

Reviewable status: 0 of 2 files reviewed, 9 unresolved discussions (waiting on @ArielElp, @bbrandtom, and @sgc-code)

assets/snip-x/paymaster_api.json line 987 at r3 (raw file):

Previously, ArielElp wrote…

Can we remove the entire field then, and assume that calldata is supposed to be encoded for Cairo1 accounts?

IMO it's weird to have all the fields there but have the version be inferred implicitly by the consumer of the spec

…atestHas'

leo-starkware

Reviewable status: 0 of 2 files reviewed, 8 unresolved discussions (waiting on @ArielElp, @bbrandtom, and @sgc-code)

assets/snip-x/paymaster_api.json line 1015 at r4 (raw file):

Previously, ArielElp wrote…

This was changed in the latest RPC to have a recursive structure, can you take it from the v0.8.0 branch?

Done.

ArielElp

Reviewable status: 0 of 2 files reviewed, 7 unresolved discussions (waiting on @bbrandtom, @leo-starkware, and @sgc-code)

assets/snip-x/paymaster_api.json line 450 at r3 (raw file):

Previously, ArielElp wrote…

Can you change to type array and items, it's also "wrong" there IMO>

Reverting, we need unknown property names here

leo-starkware

Reviewable status: 0 of 2 files reviewed, 7 unresolved discussions (waiting on @ArielElp, @bbrandtom, and @sgc-code)

assets/snip-x/paymaster_api.json line 457 at r3 (raw file):

Previously, ArielElp wrote…

Is it important to be consistent with SNIP12 here or can we keep snake case property names? if the latter, this is relevant to all the other versions as well

I think the coupling with SNIP 12 and SNIP 9 makes life easier for integrations. Keeping for now

assets/snip-x/paymaster_api.json line 847 at r3 (raw file):

Previously, ArielElp wrote…

How about a string enum with one value NO_FEE? I don't think spaces are allowed in property names

This is for consistency with proposed changes to SNIP 9

assets/snip-x/paymaster_api.json line 861 at r3 (raw file):

Previously, ArielElp wrote…

Why does the spec need to know about Cairo's representation of uint26? (part of the broader discussion on should the paymaster spec use SNIP12 terminology)

Same discussion as above re SNIP 12

ArielElp

Reviewed 1 of 2 files at r2, 1 of 1 files at r6, all commit messages.
Reviewable status: all files reviewed, 7 unresolved discussions (waiting on @bbrandtom and @sgc-code)

ArielElp

Reviewable status: all files reviewed, 3 unresolved discussions (waiting on @bbrandtom and @sgc-code)

Add paymaster API SNIP

5bf04c3

leo-starkware requested review from ArielElp and bbrandtom as code owners February 5, 2025 09:38

Add link to community forum

524340d

sgc-code reviewed Feb 5, 2025

View reviewed changes

Add 'TRACKING_ID' and endpoint 'trackingIdToLatestHash'

dcbcd07

sgc-code reviewed Feb 6, 2025

View reviewed changes

Add 'status' to 'trackingIdToLatestHash'

74fbb7a

ArielElp requested changes Feb 16, 2025

View reviewed changes

leo-starkware added 2 commits February 16, 2025 15:52

Remove INVALID_REQUEST_PAYLOAD

d4de48c

Fix TRACKING_ID and remove Cairo 0 from deployment data

cb5672a

leo-starkware commented Feb 16, 2025

View reviewed changes

ArielElp requested changes Feb 16, 2025

View reviewed changes

leo-starkware commented Feb 16, 2025

View reviewed changes

leo-starkware commented Feb 17, 2025

View reviewed changes

Add recursive transaction error, update description of 'trackingIdToL…

6917249

…atestHas'

leo-starkware commented Feb 17, 2025

View reviewed changes

ArielElp reviewed Feb 20, 2025

View reviewed changes

Remove endpoint and component

9105831

leo-starkware commented Feb 25, 2025

View reviewed changes

ArielElp reviewed Feb 25, 2025

View reviewed changes

ArielElp approved these changes Feb 25, 2025

View reviewed changes

leo-starkware added 2 commits February 25, 2025 15:19

Assign SNIP number

14a7b89

Assign SNIP number in .md

63a7df4

leo-starkware merged commit 2a11ffe into main Feb 25, 2025

github-actions bot locked and limited conversation to collaborators Feb 27, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add paymaster API SNIP #132

Add paymaster API SNIP #132

leo-starkware commented Feb 5, 2025 •

edited by ArielElp

Loading

sgc-code Feb 5, 2025

leo-starkware Feb 6, 2025

sgc-code Feb 5, 2025

leo-starkware Feb 6, 2025

sgc-code Feb 6, 2025

leo-starkware Feb 6, 2025

sgc-code Feb 6, 2025

leo-starkware Feb 6, 2025

leo-starkware Feb 9, 2025

ArielElp left a comment

leo-starkware left a comment

ArielElp left a comment

leo-starkware left a comment

leo-starkware left a comment

leo-starkware left a comment

ArielElp left a comment

leo-starkware left a comment

ArielElp left a comment

ArielElp left a comment

Add paymaster API SNIP #132

Add paymaster API SNIP #132

Conversation

leo-starkware commented Feb 5, 2025 • edited by ArielElp Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ArielElp left a comment

Choose a reason for hiding this comment

leo-starkware left a comment

Choose a reason for hiding this comment

ArielElp left a comment

Choose a reason for hiding this comment

leo-starkware left a comment

Choose a reason for hiding this comment

leo-starkware left a comment

Choose a reason for hiding this comment

leo-starkware left a comment

Choose a reason for hiding this comment

ArielElp left a comment

Choose a reason for hiding this comment

leo-starkware left a comment

Choose a reason for hiding this comment

ArielElp left a comment

Choose a reason for hiding this comment

ArielElp left a comment

Choose a reason for hiding this comment

leo-starkware commented Feb 5, 2025 •

edited by ArielElp

Loading