| VIP | Title | Author | Category | Status | CreatedAt |
|---|---|---|---|---|---|
201 |
Simple Gas Payer Standard |
Xiqing Chu <[email protected]> & Mog Lu <[email protected]> |
Application |
Final |
2020-09-11 |
This document specifies a simple standard protocol between two parties who wish to conduct a designated gas paying process described in VIP-191 on Vechain. Both the sender and the gas payer of the transaction shall adhere to the general rules listed in this document.
The fee delegation feature of Vechain has gained wide attention and became adopted solutions for the enterprises to run their applications on Vechain with the emerging of requests for a fast and smoother on-chain transactional experience.
While the feature is preliminarily used in Vechain ToolChain, potential has been laid out, for it to be integrated into broader on-chain decentralized applications such as Uniswap, wallets, and online games.
However, one of the critical challenges shall be addressed before it touches the wider audience is to ensure the interoperability of transaction senders and different delegation services and minimize the effort of switching to a new service provider.
This proposal encourages a common interface for developers to implement a fee delegation service.
The two parties participating are the transaction sender and the gas payer of the transaction. A simple exchange of information should suffice the process. We denote the sender as sender endpoint and the gas payer as authorization endpoint.
The sender prepares a raw transaction to be signed by the gas payer. The full transaction body and the origin of the transaction should be disclosed to the authorization endpoint. Upon receiving the response and the signature from the gas payer, the sending endpoint is responsible for relay the transaction to Vechain blockchain.
Summary:
- Sender Endpoint prepares the transaction.
- It requests the delegation signature from the remote server.
- It decides to transmit the assembled transaction to Vechain Blockchain or discard it.
The authorization endpoint is an online service to sign delegated transactions. It MAY has a client registration and screening to prevent the abuse of the service. Upon receiving the request from the sender, it inspects the transaction and decides to sign it or reject it. It MUST NOT modify the transaction.
Summary:
- Authorization Endpoint receives the request for signing.
- It signs the transaction or rejects it.
- It sends the response back to the sender.
+--------------------+ +-----------------+ +------------------------+
| Vechain Blockchain | | Sender Endpoint | | Authorization Endpoint |
+---------+----------+ +--------+--------+ +-----------+------------+
| | |
| | |
| | |
| | A) Request for signature |
| +------------------------------>
| | |
| | |
| | | (B) Inspect request
| | |
| | C) Respond with |
| | gas payer's signature |
| | (or deny) |
| <------------------------------+
| | |
| | |
| | |
| | |
| | |
| D) Transmit Transaction | |
<------------------------------+ |
| | |
| | |
+ + +
The general working flow is described in VIP-191 with a details layout in the following steps:
A) The sender endpoint initiates a request. The request includes a origin address and an rlp-encoded full transaction. The request is sent to the authorization endpoint (in the form of a predefined URI).
Request Params
| name | description |
|---|---|
| origin | String. The origin of the transaction, address type. |
| raw | String. RLP-encoded raw transaction. Prefixed with '0x'. |
Request Example
POST /sign HTTP/1.1
Host: server.example.com
Content-Type: application/json;charset=UTF-8
{
"origin": "0xDe9daCD226e1CE48036c87Cfd956bf0229d2475d",
"raw": "0xf8550184aabbccdd20f840df947567d83b7b8d80addcb281a71d54fc7b3364ffed82271086000000606060df947567d83b7b8d80addcb281a71d54fc7b3364ffed824e208600000060606081808252088083bc614ec101"
}In order to obtain the rlp-encoded raw transaction, the sender shall use a specific tool to do so, for example:
Encoded Raw Transaction Example
from thor_devkit import transaction
delegated_body = {
"chainTag": 1,
"blockRef": "0x00000000aabbccdd",
"expiration": 32,
"clauses": [
{
"to": "0x7567d83b7b8d80addcb281a71d54fc7b3364ffed",
"value": 10000,
"data": "0x000000606060"
}
],
"gasPriceCoef": 128,
"gas": 21000,
"dependsOn": None,
"nonce": 12345678,
"reserved": {
"features": 1
}
}
delegated_tx = transaction.Transaction(delegated_body)
raw = '0x' + delegated_tx.encode().hex()B) The authorization endpoint authenticates the caller, then inspects the content of the transaction body. It establishes whether to grant or deny the signing request.
C) Assuming the signature is granted, then the response will be sent to the sender endpoint with the gas payer address, payer signature. If the request is denied, the error response will be sent.
Success Response Params
| name | description |
|---|---|
| signature | String. 65 bytes of signature, in hex format (132 chars). Prefixed with '0x'. |
Success Response Example
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"signature": "0xf8fe82c74f9e1f5bf443f8a7f8eb968140f554968fdcab0a6ffe904e451c8b9244be44bccb1feb34dd20d9d8943f8c131227e55861736907b02d32c06b934d7200"
}Responses with HTTP status code other than 200 is considered an error.
To support the client in error handling the response can optionally be of Content-Type: application/json and contain an error message.
Error Response Params
| name | description |
|---|---|
| message | String. Optional message with detailed information about the failed signed request. Human readable. |
| code | String. Optional identifier of an occured error. Machine readable. |
Error Response Example
HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"message": "The origin is not allowed.",
"code": "REJECTED_ORIGIN"
}D) The sender validates the transaction body and the gas payer signature, adds the sender signature, assembles a valid transaction, and transmits it to the Vechain blockchain.
To prevent the leaking of critical information like signatures, transaction body to a third party, HTTPS should be used during the entire process.
As the server is exposed online and accessed publicly, measures shall be taken to query parames the service such as limiting visiting certain sender endpoints. The service developer can utilize Oauth 2.0 to discipline the senders. For example a token in the HTTP request parames section:
POST /sign HTTP/1.1
Host: server.example.com?authorization=czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/json;charset=UTF-8
This happens when the client tries to exhaust the server's resource by issuing multiple signing requests in a short period of time. The service shall throttle such behavior and ensure availability and fairness.