https://github.com/cowprotocol/app-data
AppData Schema definitions
https://github.com/cowprotocol/app-data
Last synced: about 1 year ago
JSON representation
AppData Schema definitions
- Host: GitHub
- URL: https://github.com/cowprotocol/app-data
- Owner: cowprotocol
- License: mit
- Created: 2022-06-23T12:32:31.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2025-01-02T19:14:02.000Z (over 1 year ago)
- Last Synced: 2025-04-12T23:13:46.045Z (about 1 year ago)
- Language: TypeScript
- Size: 552 KB
- Stars: 4
- Watchers: 6
- Forks: 7
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
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](https://docs.cow.fi/cow-sdk/order-meta-data-appdata).
## Installation
```bash
yarn add @cowprotocol/app-data
```
## Usage
```typescript
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:
```js
// 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
```js
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
```js
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
```js
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.
```js
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](https://semver.org/) convention
- Just duplicate the latest version i.e. `src/schemas/.json` to `src/schemas/.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: `/v0.1.0.json`
- Add it to the main schema you just created in step 1: `"$ref": "/v0.1.0.json#"`.
- Example:
3. If you are modifying an existing meta-data
- Version it using the [semver](https://semver.org/) convention
- You will need to create the new file for the meta-data schema: `/.json`
- Update it in the main schema you just created in step 1: Set it to `"": { "$ref": "/.json#" }`
4. Modify the `compile.ts` script
- Add the exported constant with the latest version in, and the new metadata:
- For example:
4. Generate the typescript types
- Run `yarn build`
5. Make a test focusing on the new or modified meta-data:
-
- Don't forget to use the right version of the schema in your test:
6. Create the PR and document it together with the motivation for the changes