Skip to main content

Set Up an Endorsement Server

You must run an endorsement server when using the DFlow Swap API to fetch price quotes from market makers. See Order Flow Endorsement for more information on the endorsement server.

Get Started

To get started, you can run your own instance of the DFlow endorsement server. Follow instructions in the DFlow Endorsement Server repository for Steps 1 through 3. Step 4 is done using the DFlow Dashboard.

Step 1: Generate Endorsement Key​

An endorsement key is a Ed25519 keypair that your endorsement server will use to endorse your users' quote requests. It is important to keep this key secret so that only you can endorse your users' quote requests.

Step 2: Configure Your Server​

Endorsement Expiration Time​

DFlow allows you to set an expiration time for your endorsements using the expirationTimeUTC field in the endorsement object. By default, the DFlow endorsement server issues endorsements that expire in 120 seconds from the time of issuance (see below for considerations). Valid inputs are between 5 and 120 seconds. Endorsements with expiration times longer than 120 seconds are rejected.

Endorsement Object:

{
    // Base58-encoded endorsement key public key used to sign the endorsement message
    "endorser": string,
    // Base64-encoded Ed25519 signature of "{id},{expirationTime}" or "{id},{expirationTime},{retailTrader}"
    "signature": string,
    // Unique identifier for the endorsement
    "id": string,
    // Expiration time as UTC. Number of seconds since Jan 1, 1970 00:00:00 UTC.
    "expirationTimeUTC": integer,
}
Considerations When Changing Expiration

If your swap interface allows a user to sit on a firm quote for at most 30 seconds, you should have its endorsement expire at least 35 seconds in the future to ensure that your user's sendTransaction request is not rejected due to endorsement expiration. If instead, your endorsement expiration time were 20 seconds after issuance, your user could sit on the quote for 25 seconds and would be unable to send the transaction.

Note that if your application delegates transaction approval to a third-party wallet (e.g. a browser extension wallet), you need to account for additional time that the user may take when reviewing and signing the transaction in the third-party wallet UI.

Step 3: Run Your Server​

You can run your endorsement server via Docker or Node.js.

Step 4: Set Your Endorsement Key​

Set your endorsement key in your DFlow account. If you don't have a DFlow account, click Account Settings and navigate to Account to create an account. You will need USDC on DFlow to create the account.

Option 1: Account Settings​

To do this, click Account Settings and navigate to Endorsement Key to input your endorsement public key.

Option 2: When Creating An Auction​

The DFlow Dashboard will prompt you to input your endorsement public key when you create your first auction.

Rotate Your Endorsement Key​

As a best security practice (or in case your endorsement key is leaked), you can rotate your endorsement key without downtime by doing the following:

  1. Create a new endorsement key
  2. Add your new endorsement key to your DFlow account (Step 4 above)
  3. Run a new instance of the endorsement server that uses the new endorsement key (Steps 1-3 above)
  4. Shut down your old instance of the endorsement server
  5. Remove your old endorsement key from your DFlow account
Zero-Downtime Endorsement Key Rotation

DFlow only accepts endorsements that were signed by an endorsement key that is currently in your DFlow account. To avoid having your any of users' requests rejected due to a mismatched endorsement key during key rotation, you must add your new endorsement key to your DFlow account before running the new instance of the endorsement server that uses the new endorsement key. You must remove your old endorsement key from your DFlow account after shutting down your old instance of the endorsement server that uses the old endorsement key.