Cow AppData SDK

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 { MetadataApi } 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 metadataApi = new MetadataApi(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 metadataApi.generateAppDataDoc({
  appCode,
  environment,
  metadata: {
    referrer,
    quote,
    orderClass,
  },
})

// Get appData info
const { appDataContent, appDataHex, cid } = await metadataApi.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 MetadataApi directly from the main SDK:

import { MetadataApi } 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 metadataApi = new MetadataApi(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. Modify the compile.ts script

• Add the exported constant with the latest version in, and the new metadata:
  • For example: https://github.com/cowprotocol/app-data/pull/44/commits/aeef8a58e7bbd2a53664ce396011cb157a18406d

4. Generate the typescript types

• Run pnpm build

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.