Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve vip 191 docs - WIP #88

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

Improve vip 191 docs - WIP #88

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5fb1df7
chore: refactor first page vip-191 docs
fabiorigam Dec 31, 2024
0497fa3
chore: refactor vip-191 page 2
fabiorigam Dec 31, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 32 additions & 45 deletions developer-resources/vip-191-designated-gas-payer/how-to-integrate-vip-191-i.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,75 +1,62 @@
# How to Integrate VIP-191 (I)

Hi guys, welcome to this section of the tutorials. I am very excited about the new features that VeChain has introduced recently, for example, the VIP-191 fee delegation. I will quickly walk you through what it is and how to use it in the following tutorials.
This document provides an introduction to VIP-191 Fee Delegation on VeChain, explaining its purpose, significance, and potential applications. Subsequent sections will include practical examples of integrating VIP-191 into a dApp workflow.

### What is VIP-191? <a href="#what-is-vip-191" id="what-is-vip-191"></a>

In short, VIP-191 is a fee delegation proposal that gets realized on VeChain that enables the end-user to use blockchain without paying native tokens/cryptocurrencies. The fee is paid by a sponsor. To make a metaphor in real life, it is like a father as a primary credit cardholder giving his kid a secondary credit card to go shopping. All the fees incurred are paid by the father in the end.
VIP-191 is a fee delegation proposal introduced by VeChain. It enables users to interact with the blockchain without needing to pay transaction fees in native tokens. Instead, these fees are covered by a designated sponsor.

<figure><img src="https://cdn-images-1.medium.com/max/2152/1*-vWHlvBFcxlm3D_XeF6AlA.png" alt=""><figcaption><p><em>Father pays for his son’s shopping cart.</em></p></figcaption></figure>
To illustrate, consider a real-world analogy: a parent provides their child with a supplementary credit card. The child can make purchases, but the parent ultimately pays the bill.

### Why is VIP-191 Important? <a href="#why-is-vip-191-important" id="why-is-vip-191-important"></a>

Just as Ethereum has introduced **CREATE2** opcode to solve (in a weird way) the “user-onboarding” issue described in [this article](https://medium.com/coinmonks/user-on-boarding-and-create2-a67a185fd149), VeChain also realized the friction (huge obstacle, to be honest) for new users to adopt the blockchain system. For example, wallet setup, private key safekeeping, buying cryptocurrencies on exchanges, calculating transaction fees and so on.

On the developer’s side, it’s difficult to attract new users _**outside**_ the crypto community to try out the app even if it is awesome.

On the users’ side, the high setup knowledge of crypto will render them helpless before they get a taste of the awesome new app.

If the above practice continues, any blockchain will soon find the user-base is not expanding but shrinking. Only “savvy” tech users are in this game but inexperienced users are excluded outside. It’s against the “stupid and simple” norm we’ve been used to today since the Web2.0 and mobile-dominant era where apps are easy to use day by day.

This _death spiral_ needs to be stopped and replaced by an easy-to-go approach:
<figure><img src="https://cdn-images-1.medium.com/max/2152/1*-vWHlvBFcxlm3D_XeF6AlA.png" alt=""><figcaption><p><em>The sponsor pays for the user’s blockchain fees.</em></p></figcaption></figure>

> How about the users don’t worry about the fees/crypto and just go using the dApps directly?

Here comes the VIP-191 fee delegation protocol on VeChain. 😃

### Where does VIP-191 Come to Play? <a href="#where-does-vip-191-come-to-play" id="where-does-vip-191-come-to-play"></a>

Quite a few scenarios as I have observed.

I give three examples that can benefit from the fee delegation of VIP-191.
### Why is VIP-191 Important? <a href="#why-is-vip-191-important" id="why-is-vip-191-important"></a>

**1) A Standalone Web App Game.**
Adopting blockchain technology can pose significant challenges for new users, such as:

So suppose you have a web game that uses VeChain as a “points storing” database. Whenever the end-user calls your smart contract to upgrade their game hero, normally, they should pay for the transaction fee in VTHO (a gas token like ETH). However, now you have launched a “promotion” where newly registered users are allowed to try out your game 3 days free, all the transaction fees are covered by you — the developer’s big wallet.
* Setting up and managing wallets.
* Safeguarding private keys.
* Purchasing cryptocurrency.
* Understanding and paying transaction fees.

<figure><img src="https://cdn-images-1.medium.com/max/2832/1*0r9a_RmPNJqKYrWSiA6ZTA.png" alt=""><figcaption><p><em>Games use VIP-191 for promotion</em></p></figcaption></figure>
These complexities can hinder user adoption, particularly among individuals unfamiliar with blockchain concepts. For developers, this limits the potential user base, as onboarding non-technical users becomes increasingly difficult.

This will improve your exposure to non-tech users without knowing VeChain at all. And once they get addicted to the game, you can charge them a subscription fee in fiat ($5/month?) and keep sponsoring the game operation by your wallet. Win-Win.
The result is a lack of growth in user numbers, with blockchain ecosystems primarily catering to technically proficient individuals. This issue is contrary to the ease-of-use principles widely embraced in Web 2.0 and the mobile app era.

**2) Shipping & Logistics company**
VIP-191 addresses these challenges by enabling a frictionless user experience, where users can interact with dApps without requiring a detailed understanding of blockchain fees. This enhances accessibility and encourages broader adoption.

Suppose a shipping company is using the VeChain as its blockchain backbone for tracking cargos. Employees on the positions, eg. custom clearing, shipping, and inspecting need to write to the blockchain. All those operations need VTHO to fuel them. Sometimes each shipment involves up to 20–30 middlemen.
### Key Use Cases for VIP-191 <a href="#key-use-cases-for-vip-191" id="key-use-cases-for-vip-191"></a>

Instead of charging each account the employee holds with the minimum tokens they need and keeping an eye on the balance of each account, the management team can “sponsor” their employees’ actions and all the fees are deducted directly from a big wallet — the company’s operation wallet.
The following are examples of scenarios where VIP-191 fee delegation can be effectively utilized:

This improves security by eliminating the possible theft of wallets and ease the burden of balance tracking. The management team can also dynamically choose for whom and for what actions they would like to sponsor.
**1) Web Applications and Games**

<figure><img src="https://cdn-images-1.medium.com/max/3252/1*yMF-aQQtSHU1PfIlKOd2mA.png" alt=""><figcaption><p><em>Shipping Company uses VIP-191</em></p></figcaption></figure>
A game that leverages VeChain as a database for tracking points or progress would typically require users to pay VTHO for transactions.

**3) The Crypto Exchanges**
With VIP-191, developers can sponsor the transaction fees for new users as part of a promotion (e.g., a 3-day trial period). This allows users to try the application without needing prior knowledge of blockchain systems, improving accessibility and potentially increasing user engagement. Developers can later monetize the service through subscription models or other mechanisms.

Nowadays crypto exchanges use simple logic to collect ERC20/VIP-180 tokens from the end-users: It gives end-user a temp “deposit address” to transfer to. Once the user has done deposition, the exchange then fuels the account with some ETH/VTHO and then “withdraw” further to the exchange’s cold wallet for safekeeping (by initiating another transaction).
<figure><img src="https://cdn-images-1.medium.com/max/2832/1*0r9a_RmPNJqKYrWSiA6ZTA.png" alt=""><figcaption><p><em>Example: Web-based games using VIP-191 for user onboarding.</em></p></figcaption></figure>

This 2-step process can be largely improved by the VIP-191 fee delegation protocol.
**2) Logistics and Supply Chain Management**

Suppose the exchange has a hefty wallet that can sponsor the withdraw action, then the exchange can eliminate the 1st step of transferring fuel money to the deposit address (which involves a careful calculation of the fee and one online transaction which takes minutes). It can simply initiate the 2nd step withdraw immediately and let the fee be deducted from the hefty wallet, simple and elegant.
In industries such as shipping and logistics, blockchain is often used to track cargo movement. Employees at various checkpoints (e.g., customs clearance, shipping, and inspection) may need to interact with smart contracts, incurring transaction fees.

### How does VIP-191 Work? <a href="#how-does-vip-191-work" id="how-does-vip-191-work"></a>
With VIP-191, a centralized management team can sponsor these fees using a corporate wallet. This eliminates the need for employees to manage wallet balances or tokens, improving security and operational efficiency.

It is very simple.
<figure><img src="https://cdn-images-1.medium.com/max/3252/1*yMF-aQQtSHU1PfIlKOd2mA.png" alt=""><figcaption><p><em>Example: Logistics companies using VIP-191 for streamlined operations.</em></p></figcaption></figure>

As a developer, you probably already understood a normal valid transaction request is a transaction object with the sender’s signature.
### How VIP-191 Works <a href="#how-vip-191-works" id="how-vip-191-works"></a>

VIP-191 is using a specially formed signature composed by the user and the sponsor together.
VIP-191 introduces a modified transaction signature mechanism. Normally, a valid transaction contains a signature from the sender. Under VIP-191, the transaction includes a composite signature, formed by combining the user’s signature and the sponsor’s signature.

Just as the picture below has depicted, once the transaction is forged, the user extracts the hash (information digest) and signs it as normal. At the same time, the sponsor also signs the hash but with additional information “for whom”. Then we concatenate the two signatures together, then send the final composed signature along with the transaction itself, to the VeChain network.
The process is as follows:

<figure><img src="https://cdn-images-1.medium.com/max/3412/1*EqQX-xtv6RLNb0t1nUQCdQ.png" alt=""><figcaption><p><em>Concatenate Signatures to forge a VIP-191 signature</em></p></figcaption></figure>
1. The user creates a transaction and signs it.
2. The sponsor signs the transaction hash, including metadata specifying for whom the fees are being covered.
3. The two signatures are concatenated and sent to the VeChain network along with the transaction data.

### What’s next: <a href="#what-s-on-next" id="what-s-on-next"></a>
<figure><img src="https://cdn-images-1.medium.com/max/3412/1*EqQX-xtv6RLNb0t1nUQCdQ.png" alt=""><figcaption><p><em>How VIP-191 signatures are constructed.</em></p></figcaption></figure>

Thanks for reading this article.
### Next Steps <a href="#next-steps" id="next-steps"></a>

After solving the problem of “why and how”, I will set up a small example to show off how to integrate the VIP-191 to your dApp workflow. Keep reading!
This document outlined the purpose and applications of VIP-191 Fee Delegation. The next section will provide a step-by-step guide for implementing VIP-191 in your dApp workflow.
32 changes: 19 additions & 13 deletions developer-resources/vip-191-designated-gas-payer/how-to-integrate-vip-191-ii.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,22 +1,26 @@
# How to Integrate VIP-191 (II)

From the [previous](how-to-integrate-vip-191-i.md) article, we have learned the basic “terminologies” of VeChain VIP-191 fee delegation. To summarize, the process can be simply described as below:
This section continues from the [previous article](how-to-integrate-vip-191-i.md), where the fundamentals of VeChain’s VIP-191 fee delegation were introduced. Here, we will implement a practical example demonstrating the integration of VIP-191 in a dApp workflow.

1. The “user” creates a transaction body.
2. The “user” generates a “user signature”.
3. The transaction is sent to a “sponsor” to get a “sponsor signature”.
4. The two signatures are combined to forge a “final signature”.
5. The final transaction is posted to the VeChain network.
### Summary of the VIP-191 Process

To get an overview, the idea is depicting as below:
The VIP-191 process can be summarized as follows:

1. The `user` creates a transaction body.
2. The user generates a `user signature`.
3. The transaction is sent to a `sponsor` to obtain a `sponsor signature`.
4. Both signatures are combined to form a `final signature`.
5. The final transaction is submitted to the VeChain network.

The overall workflow is depicted below:

<figure><img src="https://cdn-images-1.medium.com/max/3140/1*sn2Hy9U6PYsA5xCSqspBBQ.png" alt=""><figcaption><p><em>Overview of VIP-191 Fee Delegation.</em></p></figcaption></figure>

Our example will involve a user with an “empty wallet” who tries to call a smart contract (which costs gas) then the sponsor pays for the operation. Let’s break it down step by step.
This example will simulate a user with an empty wallet attempting to interact with a smart contract. The sponsor will cover the transaction costs. The implementation steps are outlined below.

#### Deploy the Smart Contract <a href="#deploy-the-smart-contract" id="deploy-the-smart-contract"></a>
#### Deploying the Smart Contract <a href="#deploying-the-smart-contract" id="deploying-the-smart-contract"></a>

First, we need to deploy a simple contract on testnet for us to interact with. The source code of the smart contract is as simple as below. It contains a counter variable which will be increased each time the function increaseAmount is called by any user.
First, deploy a simple smart contract on the VeChain testnet. Below is the source code for the contract, which includes a counter that increments each time the `increaseAmount` function is called.

```solidity
pragma solidity ^0.5.11;
Expand All @@ -34,11 +38,13 @@ contract Hello {
}
```

Many tools can be used to deploy the smart contract, we won’t cover the process in this article, but you can read it from [this tutorial](https://medium.com/@abyteahead/how-to-fast-deploy-a-smart-contract-on-vechain-with-bare-hands-eab8d7d96b43).
For deployment instructions, refer to [this guide](https://medium.com/@abyteahead/how-to-fast-deploy-a-smart-contract-on-vechain-with-bare-hands-eab8d7d96b43).

For simplicity, this tutorial will use a pre-deployed contract on the VeChain testnet.

> Also, I have deployed it on testnet already, on address: 0x6d48628bb5bf20e5b4e591c948e0394e0d5bb078 We will go with this address in the rest of the article.
`Contract Address: 0x6d48628bb5bf20e5b4e591c948e0394e0d5bb078`.

#### Build a Transaction Body <a href="#build-a-transaction-body" id="build-a-transaction-body"></a>
#### Building a Transaction Body <a href="#building-a-transaction-body" id="building-a-transaction-body"></a>

We employ the thor-devkit.js library to help us with the building of a transaction. To call the method, we build a simple transaction like this:

Expand Down