Add VIP: Transaction URI Standard

VIPs
1

Overview

This VIP proposes a standardized URI format for representing various VeChain transactions, including payment requests in VET and VIP-180 tokens, multi-clause transactions, and fee-delegated transactions. These URIs can be embedded in QR codes, hyperlinks in web pages, emails, or chat messages to enable cross-application communication between loosely coupled applications. The format allows for instant invocation of the user’s preferred wallet application with the correct transaction parameters, requiring only confirmation by the authenticated user.

Link to PR: Add VIP: Transaction URI Standard by kyledotvet · Pull Request #89 · vechain/VIPs · GitHub

Motivation

The convenience of representing payment requests through clear, contact-less standards has been a significant factor in the adoption of digital payment methods like Apple Pay, Google Wallet, and other tap-to-pay solutions (see image of Square PoS system below). Bringing a similarly convenient mechanism to VeChain transactions would accelerate its acceptance as easy-to-use, plug-and-play platform among end-users and enterprises.

image
image1680×700 71.5 KB

Rationale

The proposed format is designed to resemble Ethereum’s ERC-681 URI format as closely as possible, while extending it to support VeChain-specific features. This approach leverages existing familiarity among users and developers while accommodating VeChain’s unique capabilities.

Key design considerations include:

  1. Compatibility with existing URI schemes where possible
  2. Support for all VeChain transaction types and features
  3. Compact representation for efficient QR code encoding
  4. Clear separation between simple and complex use cases
  5. Extensibility for future enhancements

Specification

URI Structure Visualization

vechain:0xAddress@chainTag/function?param1=value1&param2=value2#delegate=url
        |         |        |       |                            |
        |         |        |       |                            +-- Optional delegation
        |         |        |       +-- Parameters (optional)
        |         |        +-- Function name (optional)
        |         +-- Chain tag (identifies network)
        +-- Target address (contract or recipient)

Transaction Types & Examples

Simple VET Transfer

For a simple VET transfer, the URI format is:

vechain:0xRecipientAddress@chainTag?value=amountInWei

Example: Transfer 1.5 VET on the mainnet (chainTag: 0x4a):

vechain:0x98Ac46Fa6CaED2e7A867E1A717b9737F55774a03@4a?value=1.5e18

Basic Token Transfer

For ERC-20/VIP-180 token transfers, the URI format is:

vechain:0xTokenContractAddress@chainTag/transfer?address=recipientAddress&uint256=amountInTokenUnits

Example: Transfer 10 VTHO tokens:

vechain:0x0000000000000000000000000000456e65726779@4a/transfer?address=0x98Ac46Fa6CaED2e7A867E1A717b9737F55774a03&uint256=1e19

Multi-Clause Transactions

For multi-clause transactions, the URI format concatenates multiple clause definitions with a colon separator:

vechain:0xContractAddress@chainTag/function1?address=someAddress:0xOtherContractAddress@chainTag/function2?value=amountInWei

Example: Multi-clause transaction with two clauses:

vechain:0x0000000000000000000000000000456e65726779@4a/transfer?address=0x98Ac46Fa6CaED2e7A867E1A717b9737F55774a03&uint256=1e18:0x1234567890abcdef1234567890abcdef12345678@4a/transfer?address=0xabcdefabcdefabcdefabcdefabcdefabcdef&uint256=5e18

Note on QR Code Size Limitations: Multi-clause transactions can result in lengthy URIs that may exceed the practical capacity of QR codes at lower error correction levels (2,953 8-bit characters). Implementers should consider the following:

  • Use the minimum necessary error correction level for QR codes
  • For complex transactions with many clauses, consider alternative delivery methods
  • When possible, optimize parameter values for brevity (e.g., using scientific notation for large numbers)
  • Consider implementing a URI shortening service specifically for transaction URIs

Fee Delegation (VIP-191)

For transactions with VIP-191 fee delegation, the URI format includes delegation parameters:

vechain:0xContractAddress@chainTag/function?uint256=someValue#delegate=delegationUrl

Where delegationUrl is a URL of the delegation service.

Example: Fee delegation with VIP-191:

vechain:0x0000000000000000000000000000456e65726779@4a/transfer?address=0x7567d83b7b8d80addcb281a71d54fc7b3364ffed&uint256=1e18#delegate=https://delegation.service/123456
2 Likes
2

Good idea! Basically you propose a transaction builder in a QR Code?

Instead of using clear text, an encoded data could be used as well.

When using shortening service, it would be possible to also build the transaction data on demand.

If this is done, a URL like https://my.app/tx/mint could build and forward to the required transaction data.

Usually the challenge is bringing all clients together to support this due to fragmentation. With VeChain there is basically VeWorld now the dominating one, which has a QR code reader already embedded which opens the scanned website. That website could then show information or automatically initiate a transaction signing.

With this being a possibility already and strong client dominance, what would be the benefit of pure URL encoded transaction data?

2 Likes
3

I see a pure url encoded transaction builder as having two main benefits:

  1. There are no external dependencies
  2. Explicit structure for embedding/linking

Without external dependencies, you don’t have to also require a dapp to still be online to execute a transaction. This also allows transactions to be physically embedded without dependency/expiration (via a 2D or 3D printed QR code)

Having an explicitly outlined structure allows for external services and frameworks to more easily prompt a user to interface with a contract on VeChain without having to stand up a full transaction-prompting system. They can also be embedded into rich text documents via a straightforward Regex pattern.

1 Like
4

Another thought that occurred to me, is part of the protocol could be prefixing the URI with a link to download VeWorld, that way if it is scanned outside of VeWorld, it could prompt the scanner to download VeWorld to interact with the transaction.

5

Another facet of the URI could also be transaction comments. Having this baked in to the protocol would allow for more specific user prompting even in scenarios as described above:

To tie this all together, I’ll give a real-world example. I would love to do some VeChain-centric geocaching of physical (or digital) assets and combine these assets with a QR code that prompts a transaction that can be called to claim that geocached-item assets.

Having a comment could allow someone who finds the geocache to be prompted to “download the wallet to claim the 1000 VET” or something like that.

2 Likes
6

A further thought on this, I think we can prefix the URI with https://www.veworld.net/vechain:rest_of_uri_here that way if anyone scans the QR code with a regular camera, they will be prompted to download the wallet, but in VeWorld itself, the https://www.veworld.net/ can be stripped off and the rest of the URI can be read and acted upon.