Grant Application: Programmatic Orders API

Grant Title:

Programmatic Orders API

---

Author:

@bleu @yvesfracari @ribeirojose @mendesfabio

---

About You:

bleu collaborates with companies and DAOs as a web3 technology and user experience partner. We're passionate about bridging the experience gap we see in blockchain and web3. We have completed 10+ grants for CoW Protocol, including Hook dApps, Framework-agnostic SDK, Python SDK, and various Safe apps.

---

Additional Links:

Our work for CoW Protocol includes:

• [CoW] Framework-agnostic SDK: Refactored the CoW SDK to support multiple EVM adapters (ethers v5/v6, viem, wagmi), enabling framework-agnostic integration.
• [CoW] Hook dApps: Developed a suite of hook dApps integrated on the CoW Swap frontend, including liquidity pool hooks, claim airdrop, and vesting hooks.
• [CoW] Python SDK: Created a Python version of the CoW SDK for developers to query on-chain data, manage orders, and integrate with CoW Protocol's smart contracts.
• [CoW] AMM Deployer: Safe app to deploy new CoW AMM pools from a Safe Wallet.
• [CoW] Stop Loss: Safe App to create stop loss orders, during this grant we develop an API that tracks the creation of composable cow and decode the stop loss ones: https://composable-cow-api.up.railway.app/

---

Grant Category:

Core Infrastructure & Developer Tooling

---

Grant Description:

CoW Protocol supports various types of programmatic orders that enable advanced trading strategies:

• Composable CoW orders: Conditional orders like TWAP, Stop Loss, Perpetual Swap, Good After Time, and Trade Above Threshold
• Flash loan orders: AAVE integration that use helper contracts deployed via pre-hooks

As programmatic orders become available to EOAs through CoWShedForComposableCow and other mechanisms, there is a need for unified indexing infrastructure to support the CoW Swap frontend and ecosystem applications.

Currently, there is no unified infrastructure to efficiently track and query programmatic orders across all types. This creates a few problems:

• Lack of order visibility before OrderBook: Programmatic orders only become visible in the CoW Protocol OrderBook when they are actually placed and are executable. Before that, there's no centralized way to track pending orders, monitor their status, or display them to users.

• Difficult to map CoWShedForComposableCow contracts with EOAs: Each user interacts with Composable CoW through their own CoWShed proxy contract, making it challenging to establish the relationship between the proxy address and the actual EOA owner.

• Flash loan order ownership tracking: AAVE integration rely on a pattern where an EOA places an order whose owner is an undeployed helper contract, which is then deployed in a pre-hook. This enables powerful constructs but creates poor UX because it becomes harder to track the original owner of the order and show trading history.

We propose to build a Programmatic Orders API that will provide queryable access to all programmatic order data. The API, built with Ponder as the indexing framework, will:

• Index all Composable CoW orders created on supported chains with real-time monitoring
• Decode all Composable CoW order types:
  • TWAP (Time-Weighted Average Price) orders
  • Stop Loss orders
  • Perpetual Swap orders
  • Good After Time orders
  • Trade Above Threshold orders
• Track flash loan orders (AAVE integration) by linking deployed helper contracts to their rightful EOA owners
• Resolve ownership by integrating with CoW Shed to map contract addresses to EOA owners
• Provide API access via GraphQL endpoints with comprehensive querying capabilities

Flash Loan Order Indexing Approach:

For flash loan orders (AAVE integration), we need to establish a link between the deployed helper contract and the original EOA owner. Currently, there is no event that links these two addresses, so we recommend that this be added to make the indexer more efficient. However, we propose a two-workaround approach to the already executed orders:

Solution 1: Factory Event Monitoring

• Monitor AaveV3AdapterFactory.deployAndTransferFlashLoan calls where the receiver is the helper contract and the owner is the EOA who created the order
• Challenge: Requires call traces which are not supported on all chains and depends on expensive RPC calls

Solution 2: Trade Event Pattern Detection

• Listen to trade events and verify if the owner follows the helper contract pattern by calling specific ABI methods
• Challenge: Requires many RPC calls but works on all chains

---

Grant Goals and Impact:

This grant will provide critical infrastructure for CoW Protocol's programmatic order ecosystem by enabling:

• Support CoW Swap Frontend Integration: Enable the frontend to display all programmatic orders (Composable CoW and flash loan orders) to users, providing full visibility into their active, completed, and cancelled orders.
• EOA Support: As programmatic orders become available to regular wallets through CoWShedForComposableCow and helper contracts, users will need a unified way to manage and monitor their orders
• Unified Order Tracking: Support all programmatic order types:
  • Composable CoW orders (TWAP, Stop Loss, Perpetual Swap, Good After Time, Trade Above Threshold)
  • Flash loan orders (AAVE integration, generalized wrappers)
• Third-party Integration: Developers can use the same API to debug and track their own programmatic orders
• Extensible Infrastructure: Extensible architecture ready to support new programmatic order types as they are developed

---

GraphQL Schema (Draft):

The indexer will expose the following schema through a GraphQL API: https://dbdiagram.io/d/[DRAFT]-CoW-Programmatic-Orders-Indexer-6978e864bd82f5fce2c96408

Schema Design Rationale:

• Transaction: Tracks all transaction details for order creation and cancellation
• User: Can be EOAs or proxy contracts (AAVE flash loan helper or CoW Sheds). If is a proxy, it references the real owner.
• ComposableCoW: Central entity for Composable CoW orders with ownership.
• Order Type Entities: Each Composable CoW order type has dedicated fields for its specific parameters
• Token: Normalized entity to avoid data duplication and enable aggregated statistics
• Order: Links to CoW Protocol Orders (posted on the orderbook) with the entity that created that order. This is more complex on orders where the UID is not defined on the composable cow creation (like the PerpetualSwap but it could be achieved by comparing with the getTradableOrderWithSignature). This would require pooling the OrderBook historically and in realtime, which requires adaptations of the indexing framework since it is an off-chain data. Also, to minimize delay on real time indexing, we will need to perform complex optimizations on the order matching algorithm.

---

Milestones:

Milestone	Duration	Payment
Composable CoW tracking	2 weeks	6k xDAI
Flash loan order tracking & CoWShed ownership mapping	1.5 weeks	4.5k xDAI
Orderbook integration	3 weeks	9k xDAI
Review and Documentation	1.5 weeks	4.5k xDAI

Composable CoW tracking and decoding (2 weeks)

• Ponder indexer setup with PostgreSQL database
• Event listening for Composable CoW order creation and cancellation
• Historical backfilling and real-time monitoring
• Implement decoders for all five order types (TWAP, Stop Loss, Perpetual Swap, Good After Time, Trade Above Threshold)
• Integrate missing conditional orders (all except TWAP) into cow-sdk.

Flash loan and CoWShed order tracking (AAVE) (1.5 weeks)

• Flash loan order to EOA owner mapping (AAVE integration)
  • Implement factory event monitoring AaveV3AdapterFactory.deployAndTransferFlashLoan
  • Implement trade event as fallback
  • Support for contract event enhancement when available
• CoWShedForComposableCow proxy to EOA owner mapping
• Tracking CoWShed proxy deployments
• Linking proxy contracts to their controlling EOAs

Orderbook integration (3 weeks)

• Pooling of historical and realtime order book data.
• Matching of order book orders with generators.
• Linking orders to their originating programmatic orders generator
• Tracking execution status for Composable CoW orders

Review & Documentation (1.5 weeks)

• Review of CoW team and bug fixing
• Complete API documentation (GraphQL schema, examples)
• Integration guides for frontend and third-party developers
• README documentations on how to run and deploy the application

---

Funding Request:

We propose that milestone payments be released upon each milestone's approval. Plus, we request more 40k COW tokens vested over 12 months to cover ongoing maintenance on the same period.

---

Budget Breakdown:

We suggest a payment structure similar to our previous grants:

• xDAI payments for each milestone completion
• COW tokens vested over 12 months for ongoing maintenance and support
• RPC costs should be covered by the CoW Protocol by providing private RPC connection links. Ideally one RPC of each chain should be provided, however develop in just one chain is also possible.

---

Gnosis Chain Address (to receive the grant):

0x554866e3654E8485928334e7F91B5AfC37D18e04

---

Other Information:

• Other information is omitted because of the snapshot limit of 10k characters. However it can be checked on the forum post linked here.

---

Terms and Conditions:

By submitting this grant application, I acknowledge and agree to be bound by the CoW DAO Participation Agreement and the CoW Grant Terms and Conditions.