gsn

• OG-1075: ContractInteractor causes operation="getAddress", code=UNSUPPORTED_OPERATION
• Fix "BigNumber.toString does not accept any parameters" warning
• Update to TypeScript v5.2.2

⚠️ Warning! This is the first published release after internal migration from Truffle "Contract" to Ethers.js v5 "Contract" types and, consequently, from BN.js to @ethersproject/bignumber.

This may break things internally - please do report all bugs in our Discord!

Breaking changes:

OG-1012: Remove unnecessary 'LightTruffleContract' absraction and fix Ethers.js support

LightTruffleContract wrapper class was created when we transitioned from using Truffle "Contract" to using Web3 "Contract" (https://github.com/opengsn/gsn/commit/437c2e6e03d2a3d6b9083e0db4a9f54086e4e935) almost 3 years ago.

However, using the same approach with LightTruffleContract as an adapter from Ethers.js (both v5 and v6) "Contract" for a code that expects a Truffle "Contract" proved to be impractical, so instead the entire @opengsn/provider code was converted to use Ethers.js "Contract" natively.

OG-1063: Expose 'actual transaction hash' for users of Ethers.js

As Ethers.js does not expose the original JSON RPC response object returned by the underlying provider, it is impossible to add undeclared fields to it. For Ethers.js the related transaction hash is now available as an experimental getPossibleTransactionHashFromRequestId() function.

Note that the function may not work in case the Relay Server decided to pay a different gas price then the one specified in the RelayRequest.

OG-1065: Fix broken ephemeral keypairs flow

Previously there was an issue with using ephemeral keys with an RPC provider that refuses calls to eth_accounts. This must be resolved now.

Breaking changes:

RelayProvider.newProvider method has been deprecated to avoid confusion.
Please use one of the following:

• newWeb3Provider to create an EIP-1193 Provider compatible with Web3.js
• newEthersV5Provider to create a pair of Provider and Signer objects compatible with Ethers.js v5
• newEthersV6Provider to create a pair of Provider and Signer objects compatible with Ethers.js v6

New features:

OG-1057: Expreimental support for Ethers.js v6. Support passing an Ethers Signer objects, including Wallet, into "new provider" methods

OG-1062: Print skipped relays as errors if relay request failed

OG-1053: GsnTestEnvironment generates deterministic address for Relay Manager and Worker by default. Allow overriding Test Environment server configuration parameters.

OG-1045: Estimate view call gas limit on client with the same logic the Relay Server will use

Previously this caused many errors related to maxViewableGasLimit and minViewableGasLimit parameters, and required the Paymaster and Relay Worker to have a lot of excess balance to relay transactions.

New features:

• OG-1026: Create SingletonWhitelistPaymaster

Previously, the WhitelistPaymaster was only able to serve a single dapp operator, meaning everyone who wanted to use such a Paymaster had to deploy their own instance to the selected chain.

This change introduces a SingletonWhitelistPaymaster that will be deployed on each chain together with the GSN contracts. It will allow dapp developers to sponsor transactions for specified senders, targets and methods on those targets, without having to deploy their own Paymaster. Currently only deployed on Goerli network.

• OG-1022: Publish the PermitERC20UniswapV3Paymaster

An experimental Paymaster contract that uses ERC-20 tokens with meta-transaction support via a permit() function to pay for gas.
The Paymaster maintains a positive cash-flow by converting the tokens on Uniswap v3. Currently only deployed on Goerli network.

• OG-1027: Publish the official Paymasters addresses as part of the GSN

Previously, the only way to find the official deployed addresses for GSN contracts was through the documentation page (https://docs.opengsn.org/networks/addresses.html).

Going forward, we will be adding all necessary addresses as part of the GSN NPM package. You can access the OfficialPaymasterDeployments global object, or provide an enum value of PaymasterType instead of a Paymaster address in the GSN configuration.

Warning - highly experimental feature.

Fixes and improvements:

• OG-1039: Fix "max priority fee per" exceeding "max fee per gas"

As part of adjusting its gas fees for the Relay Server's demands, the GSN provider could get itself into an invalid state.

• OG-1030: Make RelayProvider implement ExternalProvider interface

Now there is no TypeScript error when wrapping RelayProvider instance with an ethers.Web3Provider.

• OG-1031: Avoid calling to 'getAddress' on underlying provider

This issue prevented using the GSN with a JsonRpcProvider and an Ephemeral Keypair. This must be resolved.

• OG-1029: If RelayHub address is "0x00..00" on the Paymaster throw an exception

Improvements:

• Switch from Ethers.js to Web3.js to decrease the impact the GSN has on the bundle size (OG-1009)

This is a major breaking change for this version and it may actually break things.
Please report your issues here or in the Discord chat.
However, this saves ~1.1 MB of bundle size (minimized), and for those dapps who already have
Ethers.js as their dependency brings overhead of the GNS to a minimum.

• Allow adjusting the RelayRequest for the winning PingResponse (OG-1005)

Previously, the Relay Provider would decide on a gas price and skip the Relay Server
whose gas fees are above what that value.
This however often lead to the clients being unable to make a transaction completely.
With this change the client will agree to adjust a gas price up to a certain percentage.

• Enable silent as log level and add --loglevel parameter in gsn start command (OG-1008)

• Allow passing --relayUrl and --port parameters to the gsn start command (OG-1006)

Note that this issue prevented running gsn start on "Windows Subsystem for Linux"

• Implement Calldata Gas Estimation callback (OG-1000)

On some L2's, instead of calculating zero/nonzero bytes, we estimate gas by making a view call to address(0)
and get a current calldata gas cost.

• Fix issue: Relay Server gets stuck if worker balance is insufficient to boost a transaction (OG-1017)

Improvements:

1. Accept the 'signTransaction' callback as a dependency override (OG-983)

Previously, there were only two ways the GSN Provider could sign the RelayRequest: either by using an underlying Web3.js/Ethers.js provider to execute signTypedData, or by using a provided private key directly. Both methods would produce the signature compatible with the ERC-712. This is by design and is a requirement for the ERC-2770 Forwarder to verify the signature.

However, the GSN does not require a specific Forwarder implementation. The signing can be performed using different signature algorithms, or RelayRequest signature may be omitted entirely if the Recipient contract has different validation mechanisms.

Now, one can simply override the asyncSignTypedData callback and provide a custom signature function to the GSN.

2. Expose RelayRequestID to AsyncApprovalData callback (OG-946)

The RelayRequestID may be required in the Verifying Paymaster use-case to keep track of issued 'ApprovalData' signatures, so now RelayRequestID is passed to the AsyncApprovalData.

3. Separate 'deployGSN' function from 'GsnTestEnvironment' (OG-958)

Fixes:

4. Fixed "Relay Server happily prints amount of staked token even if token address is incorrect" (OG-939)

5. Rename 'GatewayForwarder' to 'TestGatewayForwarder' (OG- 957)

Note: The GSN v3.0.0-beta.2 includes breaking changes and is not compatible with v3.0.0-beta.1.

Improvements:

1. The Relay Servers now return the range of the gas fees they support in the "Ping Response"
   Previously, the users were forced to sign the same transaction multiple times only to see their requests rejected.
   Now, the Relay Clients will no longer send transactions to Relays whose acceptable gas fee ranges are invalid.

2. Enable the private RelayServer registration.
   Previously, the Relay Server would refuse to start without a configured URL, and the clients were unable to handle such servers anyway.
   Now, configuring a Relay Server without a URL is allowed and will make it invisible to the rest of the GSN network. However the Relay Clients can use the servers URL or IP address as a preferredRelays value.

3. More control over addresses your Relay Server will serve exclusively and ability to deny service to some contracts.
   Previously, the GSN Relay Servers supported only Paymasters blacklist.
   Now, the new configuration parameters are: whitelistedPaymasters, blacklistedPaymasters, whitelistedRecipients, blacklistedRecipients.

4. Made GsnDomainSeparatorType.name field configurable.
   Previously, customers of all dapps were seeing the GSN Relayed Transaction message in the MetaMask popup.
   Now you can configure it with a domainSeparatorName parameter for Relay Providers. Your application will have to register this type with the Forwarder contract.

5. Support custom derivation paths for mnemonics and custom private keys in CLI commands.
   The new command-line parameters are: --mnemonic, --derivationPath, --derivationIndex, --privateKeyHex

6. Improved WhitelistPaymaster.
   The WhitelistPaymaster allows you to configure a whitelist of senders, targets and methods on those targets.

7. The new PermitERC20UniswapV3Paymaster c
   Previously, this Paymaster performed a Uniswap swap operation on every transaction. This caused it to be very expensive to use.
   Now, the Paymaster will only perform a swap periodically. This significantly decreases the overhead of using the GSN to pay for transactions in ERC-20 tokens.

Fixes:

1. Removed calls to getNetworkType in ContractInteractor. This function works by requesting a hash of block #0, which is not available on many networks.

2. Fixed bug where eth_getTransactionByHash would return an incorrect actualTransactionHash (by akkien).

3. Fixed exception thrown in ContractInteractor in Promise.catch context meaning it was impossible to try/catch it.

4. Fixed broken global npm installation of @opengsn/cli package.

5. Fixed Relayer crashes if network supports EIP-1559 transactions but the RPC node does not support "eth_feeHistory" API.

6. Node.js specific packages no longer required by the Relay Provider, simplifying configuration for Webpack.

7. Reduced the number of RPC calls the Relay Server performs when idle. This will help with Relay Servers reaching their API key quotas and halting.

8. Fixed the parameters for 'getFeeHistory' query to be configurable and default to a correct values (5 blocks, 50%) instead of incorrect (1 block, 0.5%). This might have affected your Relay Server causing it to refuse legitimate transactions due to gas fees range being incorrect.

And a lot of more minor bug fixes.

1. Added support for EIP-1559 transactions

Now the GSN allows users and relays to set ‘maxFeePerGas’ and ‘maxPriorityFeePerGas’ allowing them to save on transaction fees.

2. Added support for L2 rollups and side chains with better Relayer Server lookup

Our new Relayer Server lookup is based on on-chain storage so that the GSN clients no longer need to rely on emitted events to find recently registered Relayer Servers. This allows the GSN to run smoothly on L2 rollups and significantly improves lookup speed, client responsiveness and stability under high load on all chains.

3. Added support for L2 rollups and side chains with different calldata cost structure

Now the GSN will have clients estimate and sign the cost of a transaction’s calldata separately from the transaction’s execution gas limit. This allows the GSN to support L2 rollups and other networks which have different fee cost structure for calldata and execution.

4. Avoid asking the client to sign anything for transactions destined to fail

Now the GSN will perform an “unsigned dry-run” view call of the transaction that the user is trying to send during the initialization stage without asking for the user's signature. In case the transaction reverts in this view call, there is no need to request the signature as we already know the revert reason.

5. Added support for Relayer operators to stake in ERC-20 tokens

Now the GSN will allow Relayer Server operators to put stake in select ERC-20 tokens. This will allow using stablecoins to set a stake size, which will prevent floating exchange rates affecting the security assumptions of the network.

6. Added a stable transaction ID for GSN meta-transactions

Previously, the transactions sent through the GSN were identified with a regular transaction hash. This created a problem in case the Relayer had to modify the gas price of a transaction, which led to change in the transaction hash and potentially making the relayed transaction invisible to the client. Now transactions will be discoverable by the clients using an artificial meta-transaction ID.

7. Implemented a fair relayer selection algorithm

Now all relays will have to charge the same fee and the clients by default will pick a random relayer out of the registered ones. This prevents a situation where all traffic flows through a couple of relayers and hopefully makes running a relayer a much more interesting task.

8. Better support for Ethers.js Contracts and Signers

The Ethers.js package supports wrapping a Web3.js-style provider like RelayProvider out-of-the-box. This has allowed the GSN 2.0 to work with Ethers.js projects but made it inconvenient.
In GSN 3.0 we have added wrapContract and wrapSigner functions to the GSN to allow you to connect an individual Ethers.js contract or signer via GSN. (This feature is experimental).

9. Added support for ERC-165 interface check

Now all smart contracts of the GSN, including Paymasters, implement ERC-165 preventing dapp developers and Relayer operators from making mistakes in configuration.

10. Multiple bug fixes and minor improvements

This is a maintenance release for the RelayProvider and relayer service.

Changes:

Client:

Support hardware wallets: Support Ledger and Trezor One (needs latest firmware update) (#735)
Fixed relayers selection mechanism (#718)

Relayer:

Fix relayer transaction boosting (#708 )

This is a maintenance release for the RelayProvider and relayer service.

Relayer Changes:

• Pagination for client and server log queries (#637) - to support networks that don't allow getLogs from block:1
• Server registration fix - validate stake before attempting to register/add workers (#647)
• Server keeps running after unstake to ensure it sends all funds to the owner (#655)
• Server tx boosting fixes (#657) (#696)
• Adding ownerAddress as required configuration parameter to the server (#665)
• Adding http request ‘/stats’ for basic availability information (#666)
• Server DB file size fix (#696)

Contract Changes

• Upgrading contracts to Solidity 0.8
• License change to MIT
• BaseRelayRecipient: now requires _setTrustedForwarder(f) instead of setting directly trustedForwarder=f
• Adding sample paymasters package to main repo (and deprecated the gsn-paymasters git repo)

This is the latest version deployed on the Ethereum mainnet, including contracts, client and relay servers.
The audits folder includes the security audit reports by Least Authority and Chainsafe.

This is the first release with a monorepo project structure. The old @opengsn/gsn package is now deprecated, instead every component is published separately on npm:

@opengsn/contracts
@opengsn/provider
@opengsn/relay
@opengsn/cli

Client Changes

A client must import the @opengsn/provider package instead of @opengsn/gsn.

Relay Server Changes

The relayer code is published as @opengsn/relay

The opengsn/jsrelay docker container we maintain is still the recommended way to run the relay server.

The Relay Server now needs to know its owner in advance. Its configuration must have a new item:

   "ownerAddress": "0x..."

CLI changes

The gsn relayer-register tool now verifies that the relayer it attempts to register indeed has the correct owner address, and refuses to send funds to it otherwise.

Experimental gsn status command is created.

Contract Changes

• The import statements for Recipients and Paymasters smart-contracts should be changed to:

import "@opengsn/contracts/src/BaseRelayRecipient.sol";
import "@opengsn/contracts/src/BasePaymaster.sol";

In the version string (versionRecipient or versionPaymaster), the version string must conform to SemVer and start with "2.2."

• Solidity compiler version bumped to 0.7.6
• Staking for relay on StakeManager now has to be authorized by the Relay Server.
• Penalization of illegal transactions now uses a commit-reveal scheme to prevent front-running. Penalization of EIP-2930 transaction types added in Berlin is now supported.

This a new client and relayer release.

This new version is fully compatible with previous versions (that is, newer client can use older relayers, and vice-versa)

Client Changes

• We try to make creation simpler. a relayer is now created with a helper function:

   const gsnProvider = await RelayProvider
      .newProvider( provider,  { paymasterAddress: ..., }  )
      .init()

• the resolveConfigurationGSN,configureGSN methods are now removed completely from the API, as they became internal methods of the relay client.
• logger configuration are packed into inner structure. so to set logs to error only, you need to specify:
  loggerConfiguration: {logLevel: 'error'},
• loggerURL was added in previous release. now it is moved into the loggerConfiguration block.

Relay modifications (note that these items were reported on the unpublished 2.0.3 relay version)

• gasPriceOracle - relayer can use an external gas-price oracle, instead of relying on the Node's getGasPrice(). See https://github.com/opengsn/gsn/pull/526
• support loggerUrl (like the client) to redirect logs to a centralized logger, for trouble-shooting.
• Several security enhancements:
  • Paymaster reputation mechanism
  • Improved boosting mechanism (after gas-price fluctuations):

Contracts

There are no contract changes. the new client and relayers are fully compatible with the deployed contacts (and also previous relayers/clients)

This a new client library release.

Client Changes

• Added a simpler way to initialize the provider:

  gsnProvider = await RelayProvider( provider,  { paymasterAddres: ..., }  ).init()
  

• This is actually 2 changes:

  • No longer need to provide full configuration (e.g. using resolveConfigurationGSN()/configureGSN()) before passing the configuration to the provider.
  • added explicit async init() function (which resolves any missing configuration parameters).
    This init method is called automatically by first "send()" operation - But it is much better to call it explicitly, even if in the background, so that the first transaction will execute faster.
  • The "old" way of using the RelayProvider still works, it is just less efficient (requires async call before creating the provider, and still defers some of the initialization to the first call of "send()"

• added loggerUrl configuration param, to allow centralized logger for troubleshooting.

• the logLevel parameter now receives textual values "error/warning/info/debug" and not numeric.
  the default is still "error" (used to be 5), which means only errors are logged.

• auditorsCount : a mechanism for the client to verify its server's response: the client select other relayer(s) to verify the relayer didn't try to "cheat". The default is "1". set this parameter to zero (e.g. on testnets) to prevent sending the request through another relayer.

• added registerEventListener(), to let the client receive events on the progress of the GSN event handling.

• Better error handling of failed requests.

Relay modifications:

• gasPriceOracle - relayer can use an external gas-price oracle, instead of relying on the Node's getGasPrice(). See https://github.com/opengsn/gsn/pull/526
• support loggerUrl (like the client) to redirect logs to a centralized logger, for trouble-shooting.
• Several security enhancements:
  • Paymaster reputation mechanism
  • Improved boosting mechanism (after gas-price fluctuations):

Contracts

There are no contract changes. the new client and relayers are fully compatible with the deployed contacts (and previous relayers/clients)

This is an official release of the GSN network

Deployed contracts:

Contracts version is "2.0.0". Relayer (server) and RelayProvider(client) versions are 2.0.1

How to use these addresses?

A client must configure a paymaster that is willing to pay for its gas.
On test networks, you can use the "accept-everything" samples below.

When writing a contract, you must initialize its trustedForarder address.
If you write a paymaster, it should define the paymaster and relayhub it supports.

Ropsten

Rinkeby

Kovan

Goerli

Mainnet

(no "Accept-Everything" paymaster, as its real money here..)

Major change for the contracts:

Major Paymaster change:

Removed Paymaster.acceptRelayedCall
This reduce the gas cost of request (no double check for signature, nonce) and simplifies paymaster implementation.

• now the paymaster decide in its preRelayedCall whether to accept the call or not. You don't need a separate "view verifier" function. e.g. can call mytoken.transferFrom(req.from, address(this), preCharge) instead of verifying separately that the caller has balance, has approval, etc.
• paymaster needs also to call _verifyForwarder() - but actual signature, nonce check are done later (and correctly refuse the request if they fail)

Generic Forwarder

the trustedForwarder is no longer GSN specific: This also means that a "recipient" contract trusting the forwarder will continue to work with future GSN version which might modify request structure (or other relaying network)

Client configuration

As the bare-minimum, the client can be configured with the paymaster address. From there, the resolveConfigurationGSN() can build the configuration required by the RelayProvider

Development environment

Added simple ways to start GSN for testing (deploy contracts and start a relayer), on top of existing "ganache" instance:
from command-ilne: npx gsn start
from the test file itself: GsnTestEnvironment.startGsn()

• Added 'forwarder' to the signed RelayRequest struct
• Made 'canRelay' method of RelayHub internal
• All contracts now expose semver-compatibe 'versionX' field
• Relay Server source code migrated to TypeScript
• Implemented Batched Forwarder
• Added SPDX license comments to all contracts
• Added support for providing BIP39-compatible mnemonic to CLI commands
• Fixed error preventing this module to be imported in TypeScript projects