Skip to main content

Getting Started

Broadcast batched ERC2771 meta transactions for EVM Security Token (v4 and later) via a custom forwarder contract.

Feature Overview​

Non-Sequential Nonces​

The forwarder contract doesn't require sequential nonces, enforcing only nonce uniqueness. This allows for high-scale parallelization of transaction signing.

Batching​

Incoming meta transactions are dynamically batched (based on a time window or a maximum batch size) and sent to the forwarder contract in a single transaction. This further increases the throughput of the system.

Status Callbacks​

The API accepts a callback URL which is used to deliver status updates for transaction execution.

Architecture Overview​

Sequence Diagram​

Interaction Flow​

Below is a step-by-step breakdown of the process:

  1. Client Signer Initiates a Gasless Meta-Transaction

    • The Client Signer construct and signs a gasless ERC2771 meta-transaction, and sends it to the Client Backend. This can be done fully offline without the need to keep track of the nonce.

  2. Client Backend Relays Transaction to the Relayer API

    • The Client Backend forwards the meta-transaction to the Relayer API via an HTTP POST request, including a callback URL for status updates.

  3. Relayer API Forwards to ERC2771 Forwarder Contract

    • The Relayer API validates and batches meta-transactions, and submits them to the ERC2771 Forwarder Contract. A pool of gas-payer wallets managed by the relayer covers the transaction gas fees.

  4. ERC2771 Forwarder Contract Interacts with Security Token Contract

    • Acting on behalf of the Client Signer, the ERC2771 Forwarder Contract calls the Security Token contract, executing the desired operation as specified in the meta-transaction.

  5. Security Token Returns Response to ERC2771 Forwarder Contract

    • The Security Token contract completes the requested operation and returns the result back to the ERC2771 Forwarder Contract.

  6. ERC2771 Forwarder Contract Relays Result to Relayer API

    • The ERC2771 Forwarder Contract returns the transaction result, including the transaction hash, to the Relayer API.

  7. Relayer API Sends Result to Client Backend

    • The Relayer API sends the transaction result and hash back to the Client Backend.

Usage​

See Tooling for snippets and tools to generate key pairs, signatures, and meta transactions.

Authentication​

Requests​

Each API request must include an ed25519 public client key and a signature generated by the corresponding private key. The public key must be shared with Upside to whitelist the client, and should be rotated periodically.

Please refer to the Test Utils, API Reference, and examples below for details on how to generate and use the keys.

Callbacks​

Callbacks include X-Callback-Sig-B64 header, a base64-encoded ed25519 signature of json-canonicalized callback body.

The public key to verify the signature is available at GET /api/v1/callback_pk.

Nonce Management​

warning

To avoid double-spending, it is important to store the nonce associated with each meta-transaction (or rather, the action such transaction represents). If the execution fails, the transaction must be resubmitted with the same nonce.

Due to the nature of the blockchain and the transaction processing logic in the API, there may be situations—such as mempool congestion or runtime errors—where the API returns an error even though the transaction may still be executed or might have already been processed. In such cases, when the transaction is resubmitted with the same nonce, the Forwarder Contract will ensure that it is not executed again.

Example Transaction​

Step 1​

Generate an ed25519 key pair for the API client and share the public key with Upside.

import { createKeypair } from './createKeypair'

const keypair = createKeypair()

console.log(
  `Public Key: ${Buffer.from(keypair.publicKey).toString('base64')}`,
)
console.log(
  `Secret Key: ${Buffer.from(keypair.secretKey).toString('base64')}`,
)

Step 2​

Create signed meta transaction.

import { Wallet } from 'ethers'
import { createMetaTx } from './createMetaTx'
import { createTxDataForSetAddressPermissions } from './createTxData'

const functionName = 'setAddressPermissions'
const functionArgs = ['0x42D00fC2Efdace4859187DE4865Df9BaA320D5dB', '1', 'false']
const contractAddress = '0x42D00fC2Efdace4859187DE4865Df9BaA320D5dB'
const forwarderAddr = '0xF4258B3415Cab41Fc9cE5f9b159Ab21ede0501B1'
const forwarderChainId = 1
const signerSk = 'SIGNER_PRIVATE_EVM_KEY'
const signer = new Wallet(signerSk)

const metaTxWithSig = await createMetaTx(
  {
    from: signer.address,
    to: contractAddress,
    value: 0,
    gas: 1000000,
    nonce: new Date().getTime(),
    deadline: Math.floor(new Date().getTime() / 1000) + 1 * 60 * 60,
    data: createTxDataForSetAddressPermissions({
      destination: functionArgs[0],
      regGroup: parseInt(functionArgs[1]),
      frozen: functionArgs[2] === 'true',
    }),
    signature: '',
  },
  forwarderAddr,
  forwarderChainId,
  signer,
)

console.log(metaTxWithSig)

Step 3​

Sign and send the API request.

import { createReqSignature } from './createReqSignature'
import { sign } from 'tweetnacl'

const callbackUrl = 'https://example.org/tx-updates/1/receive'
const timestamp = new Date().getTime()
const requestBody = {
    metaTx: metaTxWithSig,
    callback: {
      url: callbackUrl,
    },
    timestamp,
  }

const keyPair = sign.keyPair.fromSecretKey(
  Buffer.from('ED_25519_SECRET_IN_BASE64', 'base64'),
)

const signature = createReqSignature(requestBody, keyPair.secretKey)
const sigB64 = Buffer.from(signature).toString('base64')
const pkB64 = Buffer.from(keyPair.publicKey).toString('base64')

const resp = await fetch('https://relayer.upside.gg/api/v1/relay_meta_tx', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Request-Pk-B64': pkB64,
    'X-Request-Sig-B64': sigB64,
  },
  body: JSON.stringify(requestBody),
})

if (resp.status !== 201) {
  throw new Error(`Failed to submit meta tx: ${await resp.text()}`)
}

Step 4​

Listen for the callback on the provided URL. The callback will include status, transaction hash, and X-Request-Sig-B64 from the original request for authentication.

app.post('/tx-updates/:id/recieve', (req, res) => {
  const { status, message, txHash, reqSignature } = req.body

  // Verify that received signature:
  // 1. Exists
  // 2. Belongs to the correct meta-tx
  // 3. Hasn't been received before

  if (verifySignature(reqSignature, req.params.id)) {
    console.log({ status, message, txHash })
    res.status(200).send('OK')
  } else {
    res.status(401).send('Unauthorized')
  }
})