@cowprotocol/app-data
v2.4.0
Published
CowProtocol AppData schema definitions
Downloads
13,098
Keywords
Readme
@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:
- Add a new version for the schema using the semver convention
- Just duplicate the latest version i.e.
src/schemas/<old-version>.json
tosrc/schemas/<new-version>.json
- 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
- 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#" }
- Modify the
compile.ts
script
- Add the exported constant with the latest version in, and the new metadata:
- Generate the typescript types
- Run
yarn build
- 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
- Create the PR and document it together with the motivation for the changes