Cow AppData SDK

Test coverage

Statements	Branches	Functions	Lines

AppData schema definitions

These schemas are used in the data encoded on appData field for CowProtocol orders.

For more details, check the docs.

Installation

pnpm add @cowprotocol/sdk-app-data

Usage

import { AppDataSdk } from '@cowprotocol/sdk-app-data'
import { EthersV6Adapter } from '@cowprotocol/sdk-ethers-v6-adapter'
import { JsonRpcProvider, Wallet } from 'ethers'

// Proper adapter initialization
const provider = new JsonRpcProvider('YOUR_RPC_URL')
const wallet = new Wallet('YOUR_PRIVATE_KEY', provider)
const adapter = new EthersV6Adapter({ provider, signer: wallet })

export const appDataSdk = new AppDataSdk(adapter)

const appCode = 'YOUR_APP_CODE'
const environment = 'prod'
const referrer = { address: `REFERRER_ADDRESS` }

const quote = { slippageBips: 1 } // Slippage percent, it's 0 to 100
const orderClass = { orderClass: 'market' } // "market" | "limit" | "liquidity"

const appDataDoc = await appDataSdk.generateAppDataDoc({
  appCode,
  environment,
  metadata: {
    referrer,
    quote,
    orderClass,
  },
})

// Get appData info
const { appDataContent, appDataHex, cid } = await appDataSdk.getAppDataInfo(appDataDoc)

// The app-data hex string (app-data part of the order struct)
console.log(appDataHex)

// Full appData content. It will be the exact string that if hashed using keccak-256 you would get the
// returned appDataHex (app-data hex part of the order struct).
console.log(appDataContent)

// IPFS's content identifier. Normally you don't need to use this.
// The app-data content can be uploaded to IPFS. If its uploaded, this CID will be the content identifier.
// This is a way to be able to connect the appDataHex (app-data hex part of the order struct) to its
// content using a decentralized system.
console.log(cid)

Using via Cow SDK

You can also import AppDataSdk directly from the main SDK:

import { AppDataSdk } from '@cowprotocol/cow-sdk'
import { EthersV6Adapter } from '@cowprotocol/sdk-ethers-v6-adapter'
import { JsonRpcProvider, Wallet } from 'ethers'

// Proper adapter initialization
const provider = new JsonRpcProvider('YOUR_RPC_URL')
const wallet = new Wallet('YOUR_PRIVATE_KEY', provider)
const adapter = new EthersV6Adapter({ provider, signer: wallet })

export const appDataSdk = new AppDataSdk(adapter)
// ... rest of the usage remains the same

Schemas

Schemas are exposed as json files, where the version is the file name:

// Getting the version v0.4.0
// If you use TypeScript, enable `resolveJsonModule` in tsconfig.
const schema = require('@cowprotocol/sdk-app-data/schemas/v0.4.0.json')

// Now you can for example run validation against a schema

Type definitions

There are also type definitions

import { v0_4_0 } from '@cowprotocol/sdk-app-data'

// Note: this example is
function createAppDataV0_4_0(appCode: v0_4_0.AppCode, metadata: v0_4_0.Metadata): v0_4_0.AppDataRootSchema {
  return {
    version: '0.4.0',
    appCode,
    metadata,
  }
}

Constants

The latest version names are exposed as constants

import {
  LATEST_APP_DATA_VERSION,
  LATEST_QUOTE_METADATA_VERSION,
  LATEST_REFERRER_METADATA_VERSION,
} from '@cowprotocol/sdk-app-data'

Utils

Get appData schema

To get a schema definition by version

import { getAppDataSchema } from '@cowprotocol/sdk-app-data'

const schema = getAppDataSchema('0.1.0')

It'll throw if the version does not exist

Validate appDataDoc

To validate a document, pass it to validateAppDataDoc. It'll return an object with a boolean indicating success and errors, if any. The version to validate against will be taken from the doc itself.

import { validateAppDataDoc } from '@cowprotocol/sdk-app-data'

let doc = { version: '0.4.0', metadata: {} }

let result = await validateAppDataDoc(doc)
console.log(result) // { success: true }

doc = { version: '0.0.0', metadata: {} }

result = await validateAppDataDoc(doc)
// Contrary to `getAppDataSchema`, invalid or non-existing schemas won't throw
console.log(result) // { success: false, errors: 'AppData version 0.0.0 doesn\'t exist'}

Contribute

Fork the repo so you can create a new PR. Then:

1. Add a new version for the schema using the semver convention

• Just duplicate the latest version i.e. src/schemas/<old-version>.json to src/schemas/<new-version>.json

2. If you are adding a new meta-data

• We create one directory per schema, so we can keep track of all versions. Create the directory and initial schema definition: <meta-data-name>/v0.1.0.json
• Add it to the main schema you just created in step 1: "$ref": "<meta-data-name>/v0.1.0.json#".
• Example: https://github.com/cowprotocol/app-data/pull/44/files#diff-7f7a61b478245dfda004f64bd68ac55ef68cbeb5d6d90d77e1cdbd2b7e1212b8R56

3. If you are modifying an existing meta-data

• Version it using the semver convention
• You will need to create the new file for the meta-data schema: <meta-data-name>/<new-version>.json
• Update it in the main schema you just created in step 1: Set it to "<meta-data-name>": { "$ref": "<meta-data-name>/<new-version>.json#" }

4. Generate the typescript types

• Run pnpm build. It auto-detects every src/schemas/v*.json file and regenerates the types, and the latest version is derived automatically (highest semver), so there is no constant to update by hand.

5. Make a test focusing on the new or modified meta-data:

• https://github.com/cowprotocol/app-data/pull/44/files#diff-e755a2ecce42f09829d5c7dc1de8853d1d00ef56eaadc2709601c87b9be8ddfbR556
• Don't forget to use the right version of the schema in your test: https://github.com/cowprotocol/app-data/pull/44/files#diff-e755a2ecce42f09829d5c7dc1de8853d1d00ef56eaadc2709601c87b9be8ddfbR11

6. Create the PR and document it together with the motivation for the changes

Note: The examples above point to the legacy app-data repository before the adapter system was introduced. For new implementations, please use the current repository with proper adapter initialization as shown in the usage examples above.