Skip to content

bh2smith/app-data

This branch is up to date with cowprotocol/app-data:main.

Folders and files

NameName
Last commit message
Last commit date

Latest commit

440b6ea · Jan 2, 2025

History

99 Commits
Mar 5, 2024
Jan 2, 2025
Sep 5, 2024
Mar 9, 2023
Oct 13, 2023
Jul 22, 2022
Jun 23, 2022
Sep 5, 2024
Jan 2, 2025
Mar 9, 2023
Jul 14, 2022
Oct 19, 2023

Repository files navigation

@cowprotocol/app-data

AppData schema definitions

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

For more details, check the docs.

Installation

yarn add @cowprotocol/app-data

Usage

import { MetadataApi } from '@cowprotocol/app-data'

export const metadataApi = new MetadataApi()

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,
  },
})

Schemas

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

// Getting the version v0.4.0
const schema = require('@cowprotocol/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/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/app-data'

Utils

Get appData schema

To get a schema definition by version

import { getAppDataSchema } from '@cowprotocol/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/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
  1. If you are adding a new meta-data
  1. 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#" }
  1. Modify the compile.ts script
  1. Generate the typescript types
  • Run yarn build
  1. Make a test focusing on the new or modified meta-data:
  1. Create the PR and document it together with the motivation for the changes

About

AppData Schema definitions

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • TypeScript 98.9%
  • Other 1.1%