App Data

Overview

The CoW Protocol SDK provides utilities for creating, encoding, and decoding app data — metadata that attaches referral information, custom UI parameters, partner fees, and application-specific data to orders.

Key Concepts

App Data consists of three components:

AppDataDoc: A JSON document containing metadata
AppDataHash: A keccak256 hash of the document (used in orders)
AppDataCid: An IPFS Content Identifier for the document

Creating App Data

Basic Implementation

from cowdao_cowpy.app_data.app_data_doc import AppDataDoc

app_data = AppDataDoc()
app_data_hash = app_data.to_hex()
app_data_cid = app_data.to_cid()

Custom Metadata

custom_data = {
    "appCode": "MyTradingApp",
    "metadata": {
        "referrer": {
            "address": "0x1234567890abcdef1234567890abcdef12345678"
        },
        "utm": {
            "utmSource": "telegram",
            "utmMedium": "social",
            "utmCampaign": "spring2024",
            "utmContent": "My custom message"
        }
    },
    "version": "1.0.0"
}

app_data = AppDataDoc(app_data_doc=custom_data)

Utility Functions

Generate App Data

from cowdao_cowpy.app_data.utils import generate_app_data, PartnerFee

result = generate_app_data(
    app_code="MyApp",
    graffiti="Hello CoW Protocol!"
)

With Referrer

result = generate_app_data(
    app_code="MyApp",
    referrer_address="0x1234567890abcdef1234567890abcdef12345678",
    graffiti="Referral trade"
)

With Partner Fees

partner_fee = PartnerFee(
    bps=50,
    recipient="0x1234567890abcdef1234567890abcdef12345679"
)

result = generate_app_data(
    app_code="MyApp",
    partner_fee=partner_fee,
    graffiti="Partner trade"
)

Upload and Retrieval

Upload to Order Book

async def upload_app_data():
    result = generate_app_data(
        app_code="MyApp",
        graffiti="Test order"
    )

    order_book_api = OrderBookApi()

    uploaded_hash = await order_book_api.put_app_data(
        app_data=result.app_data_object,
        app_data_hash=result.app_data_hash
    )

Retrieve App Data

async def retrieve_app_data():
    order_book_api = OrderBookApi()

    app_data_hash = AppDataHash(
        root="0x971c41b97f59534448ab833b0d83f755a4bc5c29f92b01776faa3699fcb0eeae"
    )

    app_data = await order_book_api.get_app_data(app_data_hash)

IPFS CID Conversion

from cowdao_cowpy.app_data.app_data_hex import AppDataHex
from cowdao_cowpy.app_data.app_data_cid import AppDataCid

# Hex to CID
app_data_hex = AppDataHex("971c41b97f59534448ab833b0d83f755a4bc5c29f92b01776faa3699fcb0eeae")
cid = app_data_hex.to_cid()

# CID to Hex
app_data_cid = AppDataCid("f01551220971c41b97f59534448ab833b0d83f755a4bc5c29f92b01776faa3699fcb0eeae")
hex_hash = app_data_cid.to_hex()

# Fetch from IPFS
doc = await app_data_cid.to_doc()

Multi-Chain Deployment

from cowdao_cowpy.app_data.utils import build_all_app_codes, PartnerFee

partner_fee = PartnerFee(
    bps=50,
    recipient="0x1234567890abcdef1234567890abcdef12345679"
)

app_data_hash = build_all_app_codes(
    env="prod",
    app_code="MyMultiChainApp",
    referrer_address="0x1234567890abcdef1234567890abcdef12345678",
    partner_fee=partner_fee,
    graffiti="Multi-chain deployment"
)

App Data Schema

app_data_schema = {
    "appCode": "string",
    "metadata": {
        "referrer": {
            "address": "0x...",
            "version": "string"
        },
        "partnerFee": {
            "bps": 0,
            "recipient": "0x..."
        },
        "utm": {
            "utmSource": "string",
            "utmMedium": "string",
            "utmCampaign": "string",
            "utmContent": "string"
        },
        "quote": {
            "slippageBips": 0,
            "version": "string"
        }
    },
    "version": "string"
}

Utilities

Deterministic Serialization

from cowdao_cowpy.app_data.utils import stringify_deterministic

data = {"z": 3, "a": 1, "m": {"nested": "value"}}
json_string = stringify_deterministic(data)

Hash Computation

from cowdao_cowpy.app_data.utils import keccak256
import json

data = {"appCode": "MyApp"}
hash_value = keccak256(json.dumps(data).encode('utf-8'))

Existence Check

from cowdao_cowpy.app_data.utils import check_app_data_exists

exists = check_app_data_exists(order_book_api, app_data_hash)

Constants

from cowdao_cowpy.app_data.consts import (
    DEFAULT_APP_CODE,
    DEFAULT_GRAFFITI,
    DEFAULT_IPFS_READ_URI,
    DEFAULT_APP_DATA_DOC
)

Best Practices

Upload Before Use: Always upload app data to the order book before using it in orders. Solvers need to retrieve it for order validation.

Unique Hashes: Different content produces different hashes, enabling unique orders with identical token pairs
Partner Fees: Verify recipient addresses carefully; fees derive from order surplus

Use Cases

Referral tracking via referrer addresses
Partner revenue through fees
Campaign attribution using UTM parameters
Order identification with unique graffiti
Version tracking for debugging

Getting Started

Concepts

Guides

Advanced

API Reference

Overview

Key Concepts

Creating App Data

Basic Implementation

Custom Metadata

Utility Functions

Generate App Data

With Referrer

With Partner Fees

Upload and Retrieval

Upload to Order Book

Retrieve App Data

IPFS CID Conversion

Multi-Chain Deployment

App Data Schema

Utilities

Deterministic Serialization

Hash Computation

Existence Check

Constants

Best Practices

Use Cases

​Overview

​Key Concepts

​Creating App Data

​Basic Implementation

​Custom Metadata

​Utility Functions

​Generate App Data

​With Referrer

​With Partner Fees

​Upload and Retrieval

​Upload to Order Book

​Retrieve App Data

​IPFS CID Conversion

​Multi-Chain Deployment

​App Data Schema

​Utilities

​Deterministic Serialization

​Hash Computation

​Existence Check

​Constants

​Best Practices

​Use Cases

Overview

Key Concepts

Creating App Data

Basic Implementation

Custom Metadata

Utility Functions

Generate App Data

With Referrer

With Partner Fees

Upload and Retrieval

Upload to Order Book

Retrieve App Data

IPFS CID Conversion

Multi-Chain Deployment

App Data Schema

Utilities

Deterministic Serialization

Hash Computation

Existence Check

Constants

Best Practices

Use Cases