Express Backend

We will start from a simple Express backend. You can use any backend infrastructure or library of your choosing but note that current library support is limited to JavaScript/TypeScript. Install express, @ethsign/sp-sdk, and viem.

import express from "express";
const app = express()
const port = 3000

app.get('/', (req, res) => {
  res.send('Hello World!')
})

app.listen(port, () => {
  console.log(`Example app listening on port ${port}`)
})

This boilerplate code is the simplest backend you can create. It creates a new server and listens for requests on port 3000.

Initializing the Sign Protocol Client

Since we are running this code from a backend server, Sign Protocol's SDK requires you to pass in a private key account when creating your SignProtocolClient. Typically, when no account is provided, the client will use window.ethereum, which does not exist in a backend environment. Your code should look something like the following, assuming you are building on Sepolia:

import {
  SignProtocolClient,
  SpMode,
  EvmChains
} from "@ethsign/sp-sdk";
import { privateKeyToAccount } from "viem/accounts";

const privateKey = "0x..."; // account responsible for paying gas fees

const client = new SignProtocolClient(SpMode.OnChain, {
  chain: EvmChains.sepolia,
  account: privateKeyToAccount(privateKey) // required in backend environments
});

Setting Up Your Controller

Your controller will be responsible for creating the attestation. Since this is a delegate attestation, it must provide the attestation object and the delegation signature. The backend is not responsible for generating the delegation signature because the user's wallet must sign a message to retrieve the signature. Your controller should look something like the following:

app.post(
  "/delegate",
  async (req: Request<{}, {}, { attestation: Attestation; delegationSignature: string }>, res: Response) => {
    try {
      const { attestation, delegationSignature } = req.body;

      const response = await client.createAttestation(attestation, {
        delegationSignature
      });
      res.status(200).json({ message: response });
    } catch (error: any) {
      res.status(500).json({
        error: {
          message: error.message
        }
      });
    }
  }
);

(Frontend) Generating a Delegation Signature

This section must be implemented on your frontend. Delegation signatures are a mechanism to allow a third party to upload an attestation on behalf of an attester. The attester must approve (sign) the attestation that is being created to prevent fraudulent attestations. In other words, you would not want someone making attestations using your wallet address without you approving the attestation content first - unapproved attestations could pose a major security threat. After attaining a signature from the user/attester, the attestation and signature can be sent to the backend we wrote above. Your frontend code should include the following:

import {
  EvmChains,
  delegateSignAttestation
} from "@ethsign/sp-sdk";

const schemaId = "0x...";
const attestationData = {
  ...
};
const indexingValue = "0x...";

const res = await delegateSignAttestation(
  {
    schemaId: schemaId,
    data: attestationData,
    indexingValue: indexingValue
  },
  { chain: EvmChains.sepolia }
);

const attResponse = await fetch(`${YOUR_BACKEND_URL}/delegate`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ attestation: res.attestation, delegationSignature: res.delegationSignature })
});

...

// You can now use `attResponse` for anything you need in your frontend code

Recap

The general flow to create a delegated attestation using a backend is the following:

1. Generate the attestation content. This can be done on the frontend (as shown above) or on a dedicated backend (and then sent to the frontend for step 2).

2. Request a delegation signature from the user in a browser.

3. Forward the attestation and delegation signature to your dedicated backend.

4. Create the attestation, providing the attestation and delegation signature.