Merge pull request #430 from alchemyplatform/gas-manager-changes

custom rules and multi-network gas policies

account-abstraction/gas_manager_admin.yaml

@@ -14,7 +14,9 @@ paths:
     post:
       tags: ['Gas Manager Admin API Endpoints']
       summary: Create Policy
-      description: Creates a new gas manager policy with the specified rules. Returns the policy id of a successfully created policy. The newly created policy will be in the “inactive” status.
+      description: |
+        Creates a new gas manager policy with the specified rules. Returns the policy id of 
+        a successfully created policy. The newly created policy will be in the “inactive” status.
       operationId: create-policy
       security:
         - BearerAuth: []
@@ -30,21 +32,24 @@ paths:
                   default: 'My Policy'
                 policyType:
                   type: string
-                  description: Type of the policy
-                  default: 'SPONSORSHIP'
+                  description: Type of the policy (e.g. "sponsorship")
+                  default: 'sponsorship'
                 appId:
                   type: string
                   description: |
-                    ID for the app associated with the new policy. Learn how to find your app ID [here](https://docs.alchemy.com/reference/notify-api-faq#where-can-i-find-the-app-id).
+                    ID for the app associated with the new policy.
+                    Learn how to find your app ID [here](https://docs.alchemy.com/reference/notify-api-faq#where-can-i-find-the-app-id).
                   default: '6d834x9k1yh4dx6z'
                 rules:
                   description: Rules for the policy
                   $ref: './schemas.yaml#/components/schemas/Rules'
-                network:
-                  description: Network for the policy
-                  type: string
-                  default: ETH_MAINNET
-
+                networks:
+                  description: Networks for the policy
+                  type: array
+                  items:
+                    type: string
+                  default:
+                    - ETH_MAINNET
       responses:
         '200':
           description: Policy created successfully
@@ -145,6 +150,13 @@ paths:
                   default: 'My Policy'
                 rules:
                   $ref: './schemas.yaml#/components/schemas/Rules'
+                networks:
+                  description: Networks for the policy
+                  type: array
+                  items:
+                    type: string
+                  default:
+                    - ETH_MAINNET
       responses:
         '200':
           description: Policy rules replaced successfully
@@ -269,7 +281,7 @@ paths:
                       msg:
                         type: string
 
-  '/api/gasManager/policy/{id}/stats':
+  '/api/gasManager/policy/{id}/stats/details':
     get:
       tags: ['Gas Manager Admin API Endpoints']
       summary: Get Policy Stats
@@ -296,21 +308,56 @@ paths:
                   data:
                     type: object
                     properties:
-                      signaturesMined:
-                        type: integer
-                        default: 10
-                      signaturesExpired:
-                        type: integer
-                        default: 1
-                      signaturesPending:
-                        type: integer
-                        default: 1
-                      usdPending:
-                        type: string
-                        default: '25.03'
-                      usdMined:
-                        type: string
-                        default: '260.32'
+                      policyStats:
+                        type: object
+                        properties:
+                          signaturesMined:
+                            type: integer
+                            default: 0
+                          signaturesExpired:
+                            type: integer
+                            default: 0
+                          signaturesPending:
+                            type: integer
+                            default: 0
+                          usdPending:
+                            type: string
+                            default: '0.0'
+                          usdMined:
+                            type: string
+                            default: '0.0'
+                      policyNetworkStats:
+                        type: array
+                        items:
+                          type: object
+                          properties:
+                            network:
+                              type: string
+                              default: 'MATIC_MAINNET'
+                            signaturesMined:
+                              type: integer
+                              default: 0
+                            signaturesExpired:
+                              type: integer
+                              default: 0
+                            signaturesPending:
+                              type: integer
+                              default: 0
+                            usdPending:
+                              type: string
+                              default: '0.0'
+                            usdMined:
+                              type: string
+                              default: '0.0'
+                            pendingNativeToken:
+                              type: number
+                              default: 0
+                            minedNativeToken:
+                              type: number
+                              default: 0
+                            currency:
+                              type: string
+                              default: 'ETH'
                   error:
                     type: object
                     properties:

account-abstraction/schemas.yaml

@@ -7,37 +7,41 @@ components:
           type: string
           description: Maximum amount of USD that can be spent by the Gas Manager
           default: '5000.00'
+          nullable: true
         maxSpendPerSenderUsd:
           type: string
           description: Maximum amount of USD that can be spent by a single sender
           default: '100.00'
+          nullable: true
         maxSpendPerUoUsd:
           type: string
           description: Maximum amount of USD that can be spent by a single user operation
           default: '20.00'
+          nullable: true
         maxCount:
           type: string
           description: Maximum number of operations that can be sponsored through the policy
           default: '100'
+          nullable: true
         maxCountPerSender:
           type: string
           description: Maximum number of operations that can be sponsored for a single sender through the policy
           default: '2'
+          nullable: true
         senderAllowlist:
           type: array
           items:
             type: string
           description: List of addresses that are allowed to send operations
           default:
-            [
-              '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
-              '0x70997970c51812dc3a010c7d01b50e0d17dc79c8',
-            ]
+            - '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266'
+            - '0x70997970c51812dc3a010c7d01b50e0d17dc79c8'
         senderBlocklist:
           type: array
           items:
             type: string
           description: List of addresses that are not allowed to send operations
+          nullable: true
         startTimeUnix:
           type: string
           description: Unix timestamp of when the policy starts
@@ -46,10 +50,27 @@ components:
           type: string
           description: Unix timestamp of when the policy ends
           default: '1679340742'
+          nullable: true
         sponsorshipExpiryMs:
           type: string
           description: Milliseconds from signing that the sponsorship expires
           default: '600000'
+        webhookRules:
+          type: object
+          description: Make a request to your server to verify sponsorship eligibility.
+          properties:
+            webhookUrl:
+              type: string
+              format: uri
+              description: The URL to call to verify sponsorship eligibility.
+              example: "https://dashboard.alchemy.com/gas-manager/policy/create"
+            approveOnFailure:
+              type: boolean
+              description: If true, the userOp will be sponsored in the event the request fails or times out.
+              default: false
+          required:
+            - webhookUrl
+            - approveOnFailure
       required:
         - startTimeUnix
         - sponsorshipExpiryMs
@@ -71,6 +92,33 @@ components:
           default: active
         rules:
           $ref: '#/components/schemas/Rules'
+        policyName:
+          type: string
+          description: Name of the policy
+          default: 'Gas Manager Policy'
+        lastUpdatedUnix:
+          type: string
+          description: Unix timestamp of when the policy was last updated
+          default: '1674228753'
+        policyVersion: 
+          type: number
+          description: Version of the policy
+          default: 0
+        policyType:
+          type: string
+          description: Type of the policy
+          default: 'sponsorship'
+        policyState:
+          type: string
+          description: State of the policy
+          default: 'ongoing'
+        networks:
+          type: array
+          items:
+            type: string
+          description: List of networks the policy is active on
+          default:
+            - 'ETH_MAINNET'
       required:
         - policyId
         - appId
@@ -89,6 +137,7 @@ components:
         confirmedTotalUsd:
           type: string
           description: Total amount of USD that was spent. Can be null if the transaction has not been mined
+          nullable: true
         status:
           type: string
           description: Status of the sponsorship. Can be PENDING, MINED or EXPIRED
@@ -100,13 +149,15 @@ components:
           description: URL to the user operation explorer for the associated user operation
         txnHash:
           type: string
-          description: Hash of the transaction associated with the sponsorship. Can be null if the transaction has not been mined
+          description: Hash of the transaction associated with the sponsorship. Can be null if not mined
+          nullable: true
         txnExplorerUrl:
           type: string
-          description: URL to the transaction explorer for the associated transaction. Can be null if the transaction has not been mined
+          description: URL to the transaction explorer for the associated transaction. Can be null if not mined
+          nullable: true
       required:
         - sender
         - grantedAt
         - status
         - uoHash
-        - uoExplorerUrl
+        - uoExplorerUrl

evm_body.yaml

@@ -2450,6 +2450,9 @@ alchemy_requestPaymasterAndData:
           items:
             type: object
             properties:
+              webhookData:
+                type: string
+                description: Additional data you wish to include in the request, such as proof of humanity.
               policyId:
                 type: string
                 description: The policy ID
@@ -2478,6 +2481,9 @@ alchemy_requestGasAndPaymasterAndData:
           items:
             type: object
             properties:
+              webhookData:
+                type: string
+                description: Additional data you wish to include in the request, such as proof of humanity.
               policyId:
                 type: string
                 description: The policy ID
@@ -2629,7 +2635,7 @@ pm_getPaymasterData:
 
             3. **chainId** (string): The chain ID.
 
-            4. **context** (object, optional): Contains `policyId`.
+            4. **context** (object, optional): Contains `policyId` & `webhookData`.
           items:
             anyOf:
               - $ref: ./components/schemas.yaml#/UserOperationPartialWithGasFields
@@ -2644,3 +2650,6 @@ pm_getPaymasterData:
                     type: string
                     format: uuid
                     description: The gas policy ID
+                  webhookData:
+                    type: string
+                    description: Additional data you wish to include in the request, such as proof of humanity.