Add VIP: Generic Delegator standard

vips/VIP-194.md

@@ -0,0 +1,174 @@
+---
+VIP: 194
+Title: Generic Delegator Standard
+Description: Standard API and mechanism to allow users to pay transaction fees in supported tokens while the service pays VTHO to the network.
+Author: Victor Bibiano (@victhorbi), Vanja Tomic (@vanja-vechain), Giulia Argiolas (@giuliamorg92), Luca Bandini (@vombato)
+Discussions: Concept introduced with VIP-191
+Category: Application
+Status: Draft
+CreatedAt: 2026-01-23
+---
+
+## Overview
+
+This VIP defines a standard for a generic delegator service on VeChainThor, enabling users to pay transaction fees in alternative tokens (e.g., VET, B3TR) while the service itself pays VTHO to the network. The standard specifies APIs and validation rules to ensure the user pays at least the VTHO-equivalent (plus service fee) in their chosen token, with the service enforcing correct transfer clauses and amounts.
+
+## Motivation
+
+The current user experience for fee payment can be a barrier to onboarding and adoption. By allowing users to pay fees in tokens they already hold, this standard:
+- Improves onboarding and UX.
+- Enables dApps and wallets to offer seamless fee sponsorship and multi-token support.
+- Fosters interoperability and composability in the VeChain ecosystem.
+
+## Rationale
+
+The generic delegator pattern abstracts fee payment, allowing service providers to sponsor transactions in VTHO while receiving other tokens from users. This approach leverages real-time exchange rates and enforces minimum payment requirements, ensuring economic fairness and service sustainability. The design supports extensibility for future tokens and transaction models.
+
+## Specification
+
+The following specification follows a reference implementation, which is already integrated in the 2 main wallets available for VeChainThor (VeWorld and VeChain Kit).
+
+[A swagger is available here](https://mainnet.delegator.vechain.org/api).  
+
+### API Endpoints
+
+All endpoints support filtering by type, speed (as query parameters), and token (as path parameter).
+
+#### 1. Fee Estimation
+
+Estimation can be obtained either by using clauses or the raw transaction.
+
+##### 1.1 Estimate Clauses
+
+**Endpoint:**  
+`POST /estimate/clauses/:token`
+
+**Request:**  
+```json
+{
+  "signer": "0xOriginatorAddress",
+  "clauses": [
+    { "to": "0xAddress", "value": "0x...", "data": "0x..." }
+  ]
+}
+```
+
+##### 1.2 Estimate Transaction
+
+**Endpoint:**  
+`POST /estimate/transaction/:token`
+
+**Request:**  
+```json
+{
+  "origin": "0xOriginatorAddress",
+  "raw": "0xRawTransactionData"
+}
+```
+
+**Response (for both):**  
+```json
+{
+  "vthoPerGasAtSpeed": { "regular": 0.00001046, "medium": 0.000012, "high": 0.000014, "legacy": 0.00001 },
+  "estimatedGas": { "usingVtho": 56507, "usingVet": 76507, "usingB3tr": 78000, "usingSmartAccount": 57507 },
+  "rate": { "usingVtho": 1, "usingVet": 0.1, "usingB3tr": 0.0346 },
+  "transactionCost": {
+    "regular": { "usingVtho": 0.59, "usingVet": 0.07, "usingB3tr": 0.025, "usingSmartAccount": 0.028 },
+    "medium": { /* ... */ },
+    "high": { /* ... */ }
+  },
+  "serviceFee": 0.1
+}
+```
+
+#### 2. Supported Coins
+
+**Endpoint:**  
+`GET /deposit/tokens`
+
+**Response:**  
+```json
+["vet", "b3tr", "vtho"]
+```
+
+#### 3. Get Deposit Account
+
+**Endpoint:**  
+`GET /deposit/account/:token`
+
+**Response:**  
+```json
+{
+  "depositAccount": "0xDepositAccountAddress"
+}
+```
+
+#### 4. Request Signature 
+
+##### 4.1 Request a Gas Payer signature for normal transactions
+The service will add a transfer clause sending the VTHO-equivalent (plus service fee) in the selected token to the deposit account.
+
+**Endpoint:**  
+`POST /sign/transaction/:token`
+
+**Request:**  
+```json
+{
+  "raw": "0xRawTransactionData",
+  "origin": "0xOriginatorAddress"
+}
+```
+
+**Response:**  
+```json
+{
+  "signature": "0xSignature",
+  "address": "0xGasPayerAddress",
+  "raw": "0xSignedTransactionData",
+  "origin": "0xOriginatorAddress"
+}
+```
+
+##### 4.1 Request a Gas Payer signature for Smart Accounts
+
+For smart account wallets, the transaction must already include the extra transfer clause and the service will sign it.
+Everything else is the same as above.
+
+**Endpoint:**  
+`POST /sign/transaction/authorized/:token`
+
+### Requirements
+
+- The transaction must include a transfer clause sending at least the VTHO-equivalent (plus service fee) in the selected token to the delegator's deposit account.
+- The service validates the clause and amount before sponsoring the transaction.
+- If requirements are not met (missing clause or insufficient amount), the service rejects the delegation.
+
+## Standard Error Codes and Messages
+
+To ensure interoperability and predictable client behavior, the following standard HTTP error codes and messages MUST be used in API responses:
+
+| HTTP Status | Message                        | Description                                                      |
+|-------------|--------------------------------|------------------------------------------------------------------|
+| 400         | Invalid request                | The request is malformed or missing required fields.              |
+| 400         | Unsupported token              | The specified token is not supported for fee delegation.          |
+| 422         | Insufficient balance           | The user does not have enough balance to cover the required fee.  |
+| 422         | Insufficient transfer amount   | The transfer clause does not cover the VTHO-equivalent + fee.     |
+| 400         | Missing transfer clause        | The transaction is missing the required transfer clause.          |
+| 403         | Unauthorized                   | The request is not authorized or signature is invalid.            |
+| 409         | Replay attack detected         | The transaction or signature has already been used.               |
+| 500         | Internal server error          | An unexpected error occurred on the server.                       |
+
+
+## Security Considerations
+
+- It is strongly recommended for service operators to keep their signers' keys in secure enclaves.
+- Validate all requests and transfer clauses for correctness and authorization.
+- Prevent replay attacks and ensure unique signatures.
+- Limit sponsorship to supported tokens and transaction types.
+- Monitor and rate-limit API usage.
+- Ensure correct fee transfer to deposit accounts.
+- Validate ERC20 transfer amounts for fee payment clauses.
+
+## Copyright
+
+Copyright and related rights waived via CC0.