Gas Station Network (GSN)

Returns the address of the IRelayHub contract for this recipient.

Switches to a new IRelayHub instance. This method is added for future-proofing: there’s no reason to not use the default instance.

Returns the version string of the IRelayHub for which this recipient implementation was built. If _upgradeRelayHub is used, the new IRelayHub instance should be compatible with this version.

Withdraws the recipient’s deposits in RelayHub.

Derived contracts should expose this in an external interface with proper access control.

Replacement for msg.sender. Returns the actual sender of a transaction: msg.sender for regular transactions, and the end-user for GSN relayed calls (where msg.sender is actually RelayHub).

Replacement for msg.data. Returns the actual calldata of a transaction: msg.data for regular transactions, and a reduced version for GSN relayed calls (where msg.data contains additional information).

See IRelayRecipient.preRelayedCall.

This function should not be overriden directly, use _preRelayedCall instead.

See IRelayRecipient.preRelayedCall.

Called by GSNRecipient.preRelayedCall, which asserts the caller is the RelayHub contract. Derived contracts must implement this function with any relayed-call preprocessing they may wish to do.

See IRelayRecipient.postRelayedCall.

This function should not be overriden directly, use _postRelayedCall instead.

See IRelayRecipient.postRelayedCall.

Called by GSNRecipient.postRelayedCall, which asserts the caller is the RelayHub contract. Derived contracts must implement this function with any relayed-call postprocessing they may wish to do.

Return this in acceptRelayedCall to proceed with the execution of a relayed call. Note that this contract will be charged a fee by RelayHub

See GSNRecipient._approveRelayedCall.

This overload forwards context to _preRelayedCall and _postRelayedCall.

Return this in acceptRelayedCall to impede execution of a relayed call. No fees will be charged.

Emitted when a contract changes its IRelayHub contract to a new one.

Sets the trusted signer that is going to be producing signatures to approve relayed calls.

Ensures that only transactions with a trusted signature can be relayed through the GSN.

The arguments to the constructor are the details that the gas payment token will have: name and symbol. decimals is hard-coded to 18.

Returns the gas payment token.

Internal function that mints the gas payment token. Derived contracts should expose this function in their public API, with proper access control mechanisms.

Ensures that only users with enough gas payment token balance can have transactions relayed through the GSN.

Implements the precharge to the user. The maximum possible charge (depending on gas limit, gas price, and fee) will be deducted from the user balance of gas payment token. Note that this is an overestimation of the actual charge, necessary because we cannot predict how much gas the execution will actually need. The remainder is returned to the user in _postRelayedCall.

Returns to the user the extra amount that was previously charged, once the actual execution cost is known.

Returns the address of the IRelayHub instance this recipient interacts with.

Called by IRelayHub to validate if this recipient accepts being charged for a relayed call. Note that the recipient will be charged regardless of the execution result of the relayed call (i.e. if it reverts or not).

The relay request was originated by from and will be served by relay. encodedFunction is the relayed call calldata, so its first four bytes are the function selector. The relayed call will be forwarded gasLimit gas, and the transaction executed with a gas price of at least gasPrice. relay’s fee is `transactionFee, and the recipient will be charged at most maxPossibleCharge (in wei). nonce is the sender’s (from) nonce for replay attack protection in IRelayHub, and approvalData is a optional parameter that can be used to hold a signature over all or some of the previous values.

Returns a tuple, where the first value is used to indicate approval (0) or rejection (custom non-zero error code, values 1 to 10 are reserved) and the second one is data to be passed to the other IRelayRecipient functions.

acceptRelayedCall is called with 50k gas: if it runs out during execution, the request will be considered rejected. A regular revert will also trigger a rejection.

Called by IRelayHub on approved relay call requests, before the relayed call is executed. This allows to e.g. pre-charge the sender of the transaction.

context is the second value returned in the tuple by acceptRelayedCall.

Returns a value to be passed to postRelayedCall.

preRelayedCall is called with 100k gas: if it runs out during exection or otherwise reverts, the relayed call will not be executed, but the recipient will still be charged for the transaction’s cost.

Called by IRelayHub on approved relay call requests, after the relayed call is executed. This allows to e.g. charge the user for the relayed call costs, return any overcharges from preRelayedCall, or perform contract-specific bookkeeping.

context is the second value returned in the tuple by acceptRelayedCall. success is the execution status of the relayed call. actualCharge is an estimate of how much the recipient will be charged for the transaction, not including any gas used by postRelayedCall itself. preRetVal is preRelayedCall's return value.

postRelayedCall is called with 100k gas: if it runs out during execution or otherwise reverts, the relayed call and the call to preRelayedCall will be reverted retroactively, but the recipient will still be charged for the transaction’s cost.

Adds stake to a relay and sets its unstakeDelay. If the relay does not exist, it is created, and the caller of this function becomes its owner. If the relay already exists, only the owner can call this function. A relay cannot be its own owner.

All Ether in this function call will be added to the relay’s stake. Its unstake delay will be assigned to unstakeDelay, but the new value must be greater or equal to the current one.

Emits a Staked event.

Registers the caller as a relay. The relay must be staked for, and not be a contract (i.e. this function must be called directly from an EOA).

This function can be called multiple times, emitting new RelayAdded events. Note that the received transactionFee is not enforced by relayCall.

Emits a RelayAdded event.

Removes (deregisters) a relay. Unregistered (but staked for) relays can also be removed.

Can only be called by the owner of the relay. After the relay’s unstakeDelay has elapsed, unstake will be callable.

Emits a RelayRemoved event.

Returns a relay’s status. Note that relays can be deleted when unstaked or penalized, causing this function to return an empty entry.

Deposits Ether for a contract, so that it can receive (and pay for) relayed transactions.

Unused balance can only be withdrawn by the contract itself, by calling withdraw.

Emits a Deposited event.

Returns an account’s deposits. These can be either a contracts’s funds, or a relay owner’s revenue.

Checks if the RelayHub will accept a relayed operation. Multiple things must be true for this to happen: - all arguments must be signed for by the sender (from) - the sender’s nonce must be the current one - the recipient must accept this transaction (via acceptRelayedCall)

Returns a PreconditionCheck value (OK when the transaction can be relayed), or a recipient-specific error code if it returns one in acceptRelayedCall.

Relays a transaction.

For this to succeed, multiple conditions must be met: - canRelay must return PreconditionCheck.OK - the sender must be a registered relay - the transaction’s gas price must be larger or equal to the one that was requested by the sender - the transaction must have enough gas to not run out of gas if all internal transactions (calls to the recipient) use all gas available to them - the recipient must have enough balance to pay the relay for the worst-case scenario (i.e. when all gas is spent)

If all conditions are met, the call will be relayed and the recipient charged. preRelayedCall, the encoded function and postRelayedCall will be called in that order.

Parameters: - from: the client originating the request - to: the target IRelayRecipient contract - encodedFunction: the function call to relay, including data - transactionFee: fee (%) the relay takes over actual gas cost - gasPrice: gas price the client is willing to pay - gasLimit: gas to forward when calling the encoded function - nonce: client’s nonce - signature: client’s signature over all previous params, plus the relay and RelayHub addresses - approvalData: dapp-specific data forwared to acceptRelayedCall. This value is not verified by the RelayHub, but it still can be used for e.g. a signature.

Emits a TransactionRelayed event.

Returns how much gas should be forwarded to a call to relayCall, in order to relay a transaction that will spend up to relayedCallStipend gas.

Returns the maximum recipient charge, given the amount of gas forwarded, gas price and relay fee.

Penalize a relay that signed two transactions using the same nonce (making only the first one valid) and different data (gas price, gas limit, etc. may be different).

The (unsigned) transaction data and signature for both transactions must be provided.

Penalize a relay that sent a transaction that didn’t target `RelayHub’s registerRelay or relayCall.

Returns an account’s nonce in RelayHub.

Emitted when a relay’s stake or unstakeDelay are increased

Emitted when a relay is registered or re-registerd. Looking at these events (and filtering out RelayRemoved events) lets a client discover the list of available relays.

Emitted when a relay is removed (deregistered). unstakeTime is the time when unstake will be callable.

Emitted when a relay is unstaked for, including the returned stake.

Emitted when depositFor is called, including the amount and account that was funded.

Emitted when an account withdraws funds from RelayHub.

Emitted when an attempt to relay a call failed.

This can happen due to incorrect relayCall arguments, or the recipient not accepting the relayed call. The actual relayed call was not executed, and the recipient not charged.

The reason parameter contains an error code: values 1-10 correspond to PreconditionCheck entries, and values over 10 are custom recipient error codes returned from acceptRelayedCall.

Emitted when a transaction is relayed. Useful when monitoring a relay’s operation and relayed calls to a contract

Note that the actual encoded function might be reverted: this is indicated in the status parameter.

charge is the Ether value deducted from the recipient’s balance, paid to the relay’s owner.

Emitted when a relay is penalized.