@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: '0.5' }
const orderClass = { orderClass: 'market' }
const appDataDoc = await metadataApi.generateAppDataDoc({
appCode,
environment,
metadata: {
referrer,
quote,
orderClass,
},
})
const { cid, appDataHex, appDataContent } = await metadataApi.appDataToCid(appDataDoc)
const actualCid = await metadataApi.appDataHexToCid(appDataHex)
console.log(cid === actualCid)
const actualAppDatahex = await metadataApi.appDataHexToCid(cid)
console.log(appDataHex === actualAppDatahex)
const actualAppDoc = await fetchDocFromCid(cid)
expect(actualAppDoc).toBeEqual(appDataDoc)
const actualAppDoc2 = await fetchDocFromAppDataHex(appDataHex)
expect(actualAppDoc2).toBeEqual(appDataDoc)
Schemas
Schemas are exposed as json files, where the version is the file name:
const schema = require('@cowprotocol/app-data/schemas/v0.4.0.json')
Type definitions
There are also type definitions
import { v0_4_0 } from '@cowprotocol/app-data'
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)
doc = { version: '0.0.0', metadata: {} }
result = await validateAppDataDoc(doc)
console.log(result)
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
to src/schemas/<new-version>.json
- If you are adding a new meta-data
- 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
- Make a test focusing on the new or modified meta-data:
- Create the PR and document it together with the motivation for the changes