The system is designed to achieve deployments and transaction sponsorship at a low cost. The cost of the relay service provided by “sponsors” is agreed upon among the parties off-chain. The low cost of transactions on RSK contributes to keeping overall service costs low as well.
The RIF Relay system is made up for various components, some of which are essential and others which are auxiliary.
An overview of this is as follows:
On-chain, the system cannot work without its Smart Contracts, which encompass Smart Wallets plus the Relay Hub, the latter of which keeps tracks of staked relay managers.
Off-chain, at least 1 Relay Server is needed to interact with the contracts. Without a Relay Server, envelopes cannot be created and sent to the contracts.
Details for each of these components are expanded down below, as well as an introductory glossary.
|Sponsor||A third party that pays the gas consumed by a sponsored transaction (see below) by submitting it to the blockchain.|
|Sponsored Transaction||A transaction sent by the requester (see below) through the Sponsor, this type of transaction aims to separate the gas payer from the sender of the transaction.|
|Requester||It’s an EOA (see below). The requester sends a sponsored transaction to the Sponsor. They do not pay the gas with native-currency but with a token accepted by the Sponsor, if they don’t subsidize it.|
|Recipient||An abbreviation for recipient contract. It’s the destination of the requester’s transaction.|
|Envelope||Using the “envelopes” analogy, it’s the transaction, (funded with native cryptocurrency as gas) sent by the Sponsor to the blockchain, that wraps the requester’s transaction payload (sponsored transaction).|
|RIF Relay||The entire system which allows the relay of sponsored transactions.|
|DoS||A Denial of Service is an information-security threat whose goal is to become a service unavailable.|
|DeFi||An acronym for Decentralized Finance, it’s a novel form for finance based in blockchain technology.|
|EOA||An External Owned Account (EOA) is an account managed with a key, which is capable of signing and sending transactions, and paying the cost for it.|
The Relay Hub is the main on-chain component of the RIF Relay architecture. It acts as an interface with the Relay Server and the whole on-chain architecture. It manages the balances of the accounts involved and forwards Relays Requests to the rest of the contracts, and receives the Relay Request and forwards it to the Smart Wallet.
Also, the Relay Hub forms part of the relay worker’s registration process together with the Relay Managers. Furthermore, the Relay Hub keeps the balances that will be used to pay the relay workers for their transaction submission. Without enough balance in the Relay Hub to pay for the relay of a transaction the relay call will be reverted.
It’s the “contract-based account” owned by the Requester’s EOA.
Smart Wallet are contracts that verify forwarded data and subsequently invoke the recipient contract of the transaction. The smart wallet is deployed counterfactually at the moment it is needed. This happens, for instance, when a user with some token balances wants to move those tokens without spending gas, i.e. using the relay system.
It is the component that calls the Recipient contract (i.e, the
msg.sender address the Recipient will see). During the execution, the contract verifies the Relay Request and, if it’s valid, it calls the defined Recipient’s function, otherwise it reverts the invocation. The verification includes checking that the owner of the SmartWallet made the request, rejecting any request with an invalid signature, and preventing replay attacks using a nonce.
An on-chain account that has staked balance. It delegates the requests to Relay Workers, which are the actual initiators of the relay flow. Any penalization done against a Relay Worker impacts the Relay Manager’s stake. A Relay Worker can be managed by only one Relay Manager. A Relay Manager can have one or more Relay Workers. The responsibilities of the Relay Manager are: registering the Relay Server and adding relay workers, both in the Relay Hub.
An EOA that belongs to only one Relay Manager. It’s the sender of the Relay Request.
The Stake Manager supports multiple Relay Hubs, the stakers are the Relay Managers and they can authorize/de-authorize specific Relay Hubs so they can penalize the managers if needed. The staked cryptocurrency is held in the StakeManager contract.
The account staking for a specific Relay Manager for the first time becomes the owner of the stake, only this account can make subsequent stakes for this specific RelayManager.
When a Relay Manager unauthorised a Relay Hub, it means it is unstaking from it, which also means not being able to relay through that hub any more. Any balance held in the Relay Hub is sent to the original sender of the stake (the owner). Also, the workers’ balances are transferred to the stake owner, and, if configured, the Relay Manager’s balance can also be transferred to the stake owner.
Unstaking has a predefined delay (in blocks). This is intended to prevent the Relay Manager from unstaking before a slashing that was going to occur.
Abstract contracts that authorizes a specific relay or deploy request (see the Relay & Deploy Requests section).
The verifiers are abstract contracts that authorize and validate specific relay requests.
Two example implementations are provided:
Factory of Proxies to the SmartWallet logic. The Smart Wallet itself is a template with portions delegated to an optional custom logic (which is also a proxy pattern).
A simple proxy that delegates every call to a SmartWallet logic address. This proxy is the one instantiated per SmartWallet, and it will receive the SmartWallet template address as Master Copy (MC). So every call made to this proxy will end up executing the logic defined in the MC.
For the transaction execution (
execute() call), MC logic will do the signature verification and payment. Then it will execute the request, and, if custom logic was defined, it will forward the flow to it before returning.
Moreover, when a proxy to the Smart Wallet is created, it can define a custom logic that replaces what is done with the Relay Request after verifying it. With no custom logic, the recipient is called, but with custom logic, the request is delegated to the logic code.
If a custom logic is set, it can be initialized (which would impact the proxy’s state of course). This happens automatically during the deployment of the Proxy if the code of the logic contract has defined a function that conforms to the initialize(bytes) ABI.
This is an auxiliary library that bridges the Relay Request into a call of a Smart Wallet or Proxy Factory (in such case, the Request is a Deploy Request).
Detailed documentation can be found here.
The Relay Server receives sponsored transactions via HTTP.
The server has only one Relay Manager address and at least one Relay Worker, and points to just one Relay Hub.
When the Relay Server receives an HTTP Relay request, it creates an Envelope, wrapping the sponsored transaction, signs it using its Relay Worker address and then sends it to the Relay Hub contract.
The server is a service daemon, running as an HTTP service. It advertises itself (through the Relay Hub) and waits for client requests.
A relay request is the sponsored transaction, the structure used to relay a transaction. It is formed by Relay Data and Forward Request:
When the Sponsor creates an Envelope (the actual blockchain transaction to submit), it will add this Relay Request (sponsored transaction) as part of the encoded data, along with the contract and method to call (RelayHub and relayCall respectively)
The Relay request is structure that wraps the transaction sent by an end-user. It includes data required for relaying the trasaction e.g. address of the payer, address of the original requester, token payment data.
The Deploy request structure that wraps the transaction sent to deploy a Smart wallet.
A provider and wrapper for all the smart contract ABIs.
The Relay client is a typescript library for a client to access the blockchain through a relay. It provides APIs to find a relay, and to send transactions through it.
It can work access point to the Relay system. It creates, signs, and sends the Sponsored transaction, which is signed by the requester and forwarded to the Relay Server via the HTTP protocol.
It is not strictly needed since any dApp or user could relay transactions using merely a Relay Server and the smart contracts, although this is arguably harder to do manually.
The access point to the Relay system for dApps using Web3. It wraps the RelayClient to provide Web3 compatibility.
relayCallfunction of the Relay Hub contract.
The gas-less requester has a SmartWallet address where they receive tokens but don’t use them. If the requester needs to call a contract, e.g., to send the tokens to another account, they must deploy a Smart Wallet first.
relayCallfunction of the Relay Hub contract.
initializefunction in the Smart Wallet contract.
V2 deprecated the Paymaster contracts in favor of the Verifiers (see versions).
Go to top