fix: lint gasless transfer lessons

Author: onmax

src/content/tutorial/6-gasless-transfers/4-static-relay/_solution/index.js

@@ -1,5 +1,5 @@
-import { TypedRequestData } from '@opengsn/common/dist/EIP712/TypedRequestData.js'
 import { HttpClient, HttpWrapper } from '@opengsn/common'
+import { TypedRequestData } from '@opengsn/common/dist/EIP712/TypedRequestData.js'
 import { ethers } from 'ethers'
 
 // 🔐 Paste your private key from Lesson 1 here!

src/content/tutorial/6-gasless-transfers/4-static-relay/content.md

@@ -32,6 +32,13 @@ Key roles involved:
 - **Transfer contract** executes the token move and fee payment.
 - **RelayHub** validates and routes meta-transactions across the network.
 
+If you have never met OpenGSN before, keep this component cheat sheet handy:
+
+- **Forwarder:** verifies the meta-transaction signature and keeps per-sender nonces so relays cannot replay old requests. The Nimiq transfer contract bundles a forwarder implementation; see the reference in the [Nimiq Developer Center](https://developers.nimiq.com/).
+- **Paymaster:** refunds the relay in tokens such as USDT or USDC. For this tutorial the same transfer contract doubles as paymaster.
+- **RelayHub:** the canonical on-chain registry of relays. Its API is documented in the [OpenGSN Docs](https://docs.opengsn.org/).
+- **Relay server:** an off-chain service that watches the hub and exposes `/getaddr` plus `/relay` endpoints. Polygon’s networking requirements for relays are outlined in the [Polygon developer documentation](https://docs.polygon.technology/).
+
 ---
 
 ## Guardrails for This Lesson
@@ -50,7 +57,7 @@ Later lessons will replace each shortcut with production logic.
 
 Create or update your `.env` file with the following values:
 
-```bash
+```bash title=".env"
 POLYGON_RPC_URL=https://polygon-rpc.com
 SPONSOR_PRIVATE_KEY=your_mainnet_key_with_USDT
 RECEIVER_ADDRESS=0x...
@@ -64,7 +71,7 @@ RELAY_URL=https://polygon-mainnet-relay.nimiq-network.com
 
 ## Step 2: Connect and Define Contract Addresses
 
-```js
+```js title="index.js" showLineNumbers mark=6-13
 import dotenv from 'dotenv'
 import { ethers } from 'ethers'
 
@@ -82,14 +89,17 @@ console.log('🔑 Sponsor:', wallet.address)
 ```
 
 The sponsor wallet is the account that will sign messages and reimburse the relay.
+The concrete contract addresses are published in `@cashlink/currency`’s constants module and mirrored in the [Nimiq wallet gasless guide](https://developers.nimiq.com/). Always verify them against the latest deployment notes before running on mainnet.
 
 ---
 
 ## Step 3: Retrieve the USDT Nonce and Approval Amount
 
-USDT uses its own permit-style approval. Fetch the current nonce and compute how much the transfer contract is allowed to spend (transfer amount + relay fee).
+USDT on Polygon does _not_ implement the standard ERC‑2612 permit. Instead it exposes `executeMetaTransaction`, which expects you to sign the encoded `approve` call. The `nonces` counter you query below is USDT’s own meta-transaction nonce (documented in [Tether’s contract implementation](https://docs.opengsn.org/contracts/erc-2771.html)), so we can safely reuse it when we sign the approval.
+
+Fetch the current nonce and compute how much the transfer contract is allowed to spend (transfer amount + relay fee).
 
-```js
+```js title="index.js" showLineNumbers mark=3-9
 const USDT_ABI = ['function nonces(address owner) view returns (uint256)']
 const usdt = new ethers.Contract(USDT_ADDRESS, USDT_ABI, provider)
 
@@ -106,9 +116,9 @@ const approvalAmount = amountToSend.add(staticFee)
 
 ## Step 4: Sign the USDT Meta-Approval
 
-USDT on Polygon uses `executeMetaTransaction` for gasless approvals. Build the EIP-712 MetaTransaction payload and sign it.
+USDT on Polygon uses `executeMetaTransaction` for gasless approvals. Build the EIP‑712 MetaTransaction payload and sign it. Notice the domain uses the `salt` field instead of `chainId`; that is specific to the USDT contract. Compare this to the generic permit flow covered in [OpenGSN’s meta-transaction docs](https://docs.opengsn.org/gsn-provider/metatx.html) to see the differences.
 
-```js
+```js title="index.js" showLineNumbers mark=9-19
 // First, encode the approve function call
 const approveFunctionSignature = usdt.interface.encodeFunctionData('approve', [
   TRANSFER_CONTRACT_ADDRESS,
@@ -151,7 +161,7 @@ This signature allows the relay to execute the `approve` call on your behalf via
 
 Prepare the calldata the relay will submit on your behalf.
 
-```js
+```js title="index.js" showLineNumbers mark=6-14
 const TRANSFER_ABI = ['function transferWithApproval(address token, uint256 amount, address to, uint256 fee, uint256 approval, bytes32 r, bytes32 s, uint8 v)']
 const transferContract = new ethers.Contract(TRANSFER_CONTRACT_ADDRESS, TRANSFER_ABI, wallet)
 
@@ -173,9 +183,9 @@ console.log('📦 Calldata encoded')
 
 ## Step 6: Build and Sign the Relay Request
 
-The relay expects a second EIP-712 signature covering the meta-transaction wrapper. Gather the contract nonce and sign the payload.
+The relay expects a second EIP‑712 signature covering the meta-transaction wrapper. This time the domain is the **forwarder** (embedded inside the transfer contract). Gather the contract nonce and sign the payload.
 
-```js
+```js title="index.js" showLineNumbers mark=6-21
 const transferNonce = await transferContract.getNonce(wallet.address)
 
 const relayRequest = {
@@ -186,22 +196,23 @@ const relayRequest = {
     gas: '350000',
     nonce: transferNonce.toString(),
     data: transferCalldata,
-    validUntilTime: (Math.floor(Date.now() / 1000) + 7200).toString()
+    validUntil: (Math.floor(Date.now() / 1000) + 7200).toString()
   },
   relayData: {
     gasPrice: '100000000000', // 100 gwei (static!)
     pctRelayFee: '0',
     baseRelayFee: '0',
-    relayWorker: 'will_be_filled_by_relay',
+    relayWorker: '0x0000000000000000000000000000000000000000', // Will be filled by relay
     paymaster: TRANSFER_CONTRACT_ADDRESS,
-    forwarder: '0x...', //  Trusted Forwarder address
+    forwarder: TRANSFER_CONTRACT_ADDRESS,
+    paymasterData: '0x',
     clientId: '1'
   }
 }
 
 // Sign it
-const relayDomain = { name: 'GSN Relayed Transaction', version: '2', chainId: 137, verifyingContract: '0x...' }
-const relayTypes = { /* RelayRequest types */ }
+const relayDomain = { name: 'GSN Relayed Transaction', version: '2', chainId: 137, verifyingContract: TRANSFER_CONTRACT_ADDRESS }
+const relayTypes = { /* RelayRequest types – see docs.opengsn.org for the full schema */ }
 const relaySignature = await wallet._signTypedData(relayDomain, relayTypes, relayRequest)
 
 console.log('✍️  Relay request signed')
@@ -211,23 +222,28 @@ console.log('✍️  Relay request signed')
 
 ## Step 7: Submit the Meta-Transaction
 
-Use the OpenGSN HTTP client to send the request to your chosen relay.
+Use the OpenGSN HTTP client to send the request to your chosen relay. The worker nonce check prevents you from handing the relay a `relayMaxNonce` that is already stale—if the worker broadcasts several transactions in quick succession, your request will still slide in. Likewise, `validUntil` in the previous step protects the relay from signing requests that could be replayed months later.
 
-```js
+```js title="index.js" showLineNumbers mark=1-18
 import { HttpClient, HttpWrapper } from '@opengsn/common'
 
+const relayNonce = await provider.getTransactionCount(relayInfo.relayWorkerAddress)
+
 const httpClient = new HttpClient(new HttpWrapper(), console)
-const relayResponse = await httpClient.relayTransaction(process.env.RELAY_URL, {
+const relayResponse = await httpClient.relayTransaction(RELAY_URL, {
   relayRequest,
   metadata: {
     signature: relaySignature,
     approvalData: '0x',
     relayHubAddress: RELAY_HUB_ADDRESS,
-    relayMaxNonce: 999999
+    relayMaxNonce: relayNonce + 3
   }
 })
 
-const txHash = typeof relayResponse === 'string' ? relayResponse : relayResponse.signedTx
+const txHash = typeof relayResponse === 'string'
+  ? relayResponse
+  : relayResponse.signedTx || relayResponse.txHash
+
 console.log('\n✅ Gasless transaction sent!')
 console.log('🔗 View:', `https://polygonscan.com/tx/${txHash}`)
 ```
@@ -263,4 +279,4 @@ You have now:
 - ✅ Understood the flow between approval, relay request, and paymaster contract.
 - ✅ Prepared the foundation for relay discovery and fee optimization.
 
-Continue to **Lesson 4** to discover relays dynamically via RelayHub events.
+Next up, **Lesson 5** walks through discovering relays dynamically from the RelayHub and filtering them with health checks informed by the [OpenGSN relay operator guide](https://docs.opengsn.org/relay/). That will let you replace today’s hardcoded URL with resilient discovery logic.

src/content/tutorial/6-gasless-transfers/5-relay-discovery/_solution/index.js

@@ -1,6 +1,6 @@
-import { TypedRequestData } from '@opengsn/common/dist/EIP712/TypedRequestData.js'
 import { HttpClient, HttpWrapper } from '@opengsn/common'
-import { ethers} from 'ethers'
+import { TypedRequestData } from '@opengsn/common/dist/EIP712/TypedRequestData.js'
+import { ethers } from 'ethers'
 
 // 🔐 Paste your private key from Lesson 1 here!
 const PRIVATE_KEY = '0xPASTE_YOUR_PRIVATE_KEY_HERE_FROM_LESSON_1'

src/content/tutorial/6-gasless-transfers/5-relay-discovery/content.md

@@ -26,94 +26,133 @@ By the end of this lesson you will:
 - Filter out relays that are offline, outdated, or underfunded.
 - Produce a resilient fallback chain when the preferred relay fails.
 
+Before you start, skim the reference material so the field names feel familiar:
+
+- [RelayHub events in the OpenGSN docs](https://docs.opengsn.org/contracts/relay-hub.html).
+- Nimiq’s [gasless transfer architecture notes](https://developers.nimiq.com/).
+- Polygon’s [gasless transaction guidelines](https://docs.polygon.technology/).
+
 ---
 
 ## Step 1: Pull Recent Relay Registrations
 
 RelayHub emits a `RelayServerRegistered` event whenever a relay announces itself. Scan the recent blocks to collect candidates.
 
-```js
+```js title="discover-relays.ts" showLineNumbers mark=6-24
 const RELAY_HUB_ABI = ['event RelayServerRegistered(address indexed relayManager, uint256 baseRelayFee, uint256 pctRelayFee, string relayUrl)']
 const relayHub = new ethers.Contract(RELAY_HUB_ADDRESS, RELAY_HUB_ABI, provider)
 
 const currentBlock = await provider.getBlockNumber()
-const LOOKBACK_BLOCKS = 144000 // ~60 hours on Polygon
+const LOOKBACK_BLOCKS = 14400 // ~10 hours on Polygon
 
 const events = await relayHub.queryFilter(
   relayHub.filters.RelayServerRegistered(),
   currentBlock - LOOKBACK_BLOCKS,
   currentBlock
 )
 
-console.log(`Found ${events.length} relay registrations`)
+const seen = new Map()
+
+for (const event of events) {
+  const { relayManager, baseRelayFee, pctRelayFee, relayUrl } = event.args
+  if (!seen.has(relayUrl)) {
+    seen.set(relayUrl, {
+      url: relayUrl,
+      relayManager,
+      baseRelayFee,
+      pctRelayFee,
+    })
+  }
+}
+
+const candidates = Array.from(seen.values())
+console.log(`Found ${candidates.length} unique relay URLs`)
 ```
 
-Looking back roughly 60 hours balances freshness with performance. Adjust the window if you need more or fewer candidates.
+Looking back roughly 10 hours balances freshness with performance. Adjust the window if you need more or fewer candidates.
 
 ---
 
 ## Step 2: Ping and Validate Each Relay
 
 For every registration, call the `/getaddr` endpoint and run a series of health checks before trusting it.
 
-```js
-import axios from 'axios'
-
-async function validateRelay(relayUrl) {
+```js title="validate-relay.ts" showLineNumbers mark=6-29
+async function validateRelay(relay, provider) {
   try {
-    const response = await axios.get(`${relayUrl}/getaddr`, { timeout: 10000 })
-    const { relayWorkerAddress, ready, version, networkId, minGasPrice } = response.data
+    const controller = new AbortController()
+    const timeout = setTimeout(() => controller.abort(), 10_000)
+
+    const response = await fetch(`${relay.url}/getaddr`, { signal: controller.signal })
+
+    clearTimeout(timeout)
+
+    if (!response.ok)
+      return null
+
+    const relayInfo = await response.json()
 
-    // Check version
-    if (!version.startsWith('2.'))
+    if (!relayInfo.version?.startsWith('2.'))
+      return null
+    if (relayInfo.networkId !== '137' && relayInfo.chainId !== '137')
+      return null
+    if (!relayInfo.ready)
       return null
 
-    // Check network
-    if (networkId !== 137)
+    const workerBalance = await provider.getBalance(relayInfo.relayWorkerAddress)
+    if (workerBalance.lt(ethers.utils.parseEther('0.01')))
       return null
 
-    // Check worker balance
-    const workerBalance = await provider.getBalance(relayWorkerAddress)
-    const requiredBalance = ethers.utils.parseEther('0.01') // Minimum threshold
-    if (workerBalance.lt(requiredBalance))
+    const pctFee = Number.parseInt(relay.pctRelayFee)
+    const baseFee = ethers.BigNumber.from(relay.baseRelayFee)
+
+    if (pctFee > 70 || baseFee.gt(0))
       return null
 
-    // Check recent activity (skip for Fastspot relays)
-    if (!relayUrl.includes('fastspot.io')) {
-      const recentTx = await provider.getTransactionCount(relayWorkerAddress)
-      // ... validate transaction recency
+    return {
+      ...relay,
+      relayWorkerAddress: relayInfo.relayWorkerAddress,
+      minGasPrice: relayInfo.minGasPrice,
+      version: relayInfo.version,
     }
-
-    return { url: relayUrl, worker: relayWorkerAddress, minGasPrice, ...response.data }
   }
   catch (error) {
     return null // Relay offline or invalid
   }
 }
 ```
 
+`AbortController` gives us a portable timeout without extra dependencies, which keeps the sample compatible with both Node.js scripts and browser bundlers.
+
 Checks to keep in mind:
 
 - **Version** must start with 2.x to match the OpenGSN v2 protocol.
 - **Network ID** should be 137 for Polygon mainnet.
 - **Worker balance** needs enough POL to front your transaction (the example uses 0.01 POL as a floor).
-- **Recent activity** ensures the worker is still alive and signing transactions.
+- **Readiness flag** confirms the relay advertises itself as accepting requests.
+- **Fee caps** ensure you never accept a base fee or a percentage beyond your policy.
 
 ---
 
 ## Step 3: Select the First Healthy Relay
 
 Iterate through the registrations until you find one that passes validation. You can collect alternates for fallback if desired.
 
-```js
-for (const event of events) {
-  const relay = await validateRelay(event.args.relayUrl)
-  if (relay) {
-    console.log('✅ Found valid relay:', relay.url)
-    // Use this relay for your transaction
-    break
+```js title="find-best-relay.ts" showLineNumbers mark=3-14
+async function findBestRelay(provider) {
+  console.log('\n🔬 Validating relays...')
+
+  for (const relay of candidates) {
+    const validRelay = await validateRelay(relay, provider)
+    if (validRelay)
+      return validRelay
   }
+
+  throw new Error('No valid relays found')
 }
+
+const relay = await findBestRelay(provider)
+console.log('✅ Using relay:', relay.url)
 ```
 
 This simple loop already improves reliability dramatically compared to a hardcoded URL.

src/content/tutorial/6-gasless-transfers/6-optimized-fees/_solution/index.js

@@ -1,5 +1,5 @@
-import { TypedRequestData } from '@opengsn/common/dist/EIP712/TypedRequestData.js'
 import { HttpClient, HttpWrapper } from '@opengsn/common'
+import { TypedRequestData } from '@opengsn/common/dist/EIP712/TypedRequestData.js'
 import { ethers } from 'ethers'
 
 // 🔐 Paste your private key from Lesson 1 here!