feat: docs by kaze-cow · Pull Request #20 · cowprotocol/euler-integration-contracts

kaze-cow · 2026-02-11T07:04:43Z

Description

Detailed documentation (based on internal notion page which has been updated over time) covers parameters, authorization flows, transaction execution, error handling, and real-world examples for integrators and auditors.

Context

As we prepare for audit, it is good to finalize our documentation. I tried to organize the docs that we alreayd had internally into an organized, easily digested set of markdowns which will provide the best starting point for potential integrators and auditors.

01-overview.md: Architecture, wrapper patterns, and design principles
02-open-position.md: Complete guide to opening leveraged positions
03-close-position.md: Guide to closing positions with Inbox pattern
04-collateral-swap.md: Guide to swapping collateral between vaults
05-security-considerations.md: Threat model, safeguards, and best practices
docs/images/: Flowchart diagrams for each wrapper operation
Updated README.md: Concise entry point linking to documentation
Updated .gitignore: Allow documentation files to be committed

Testing Instructions

Best thing we can probably do is try using this guide in combination with the playground to try setting up new CoW orders with Euler. I have a branch feat/playground-use-staging suitable for this.

anxolin

For now I only review the OVERVIEW, I gave some feedback, in general I feel a lot of context is taken from granted.

For now maybe is fine to have these docs here, but probably we want to move to https://docs.cow.fi

Wrappers should definetly be in https://docs.cow.fi and we could reference from here.

anxolin · 2026-02-11T12:21:28Z

+
+### Base Framework: CowWrapper
+
+`CowWrapper.sol` is a self-contained abstract base contract provided by the CoW DAO which should be used for all wrappers. In particular it ensures:


I think is nice to link to the file

linked to the specific file

anxolin · 2026-02-11T12:21:48Z

+
+### EVC Integration Base: CowEvcBaseWrapper
+
+`CowEvcBaseWrapper.sol` extends `CowWrapper` with:


linked to the specific file

anxolin · 2026-02-11T12:52:53Z

+
+**Result**: User's debt is repaid and remaining collateral is returned
+
+**Example**: User closes a 5 ETH short position (ETH = $1000). Around 5000 USDC collateral is swapped to exactly the user's debt of 5 ETH. The debt is repaid, and remaining USDC ($1000) is returned to the owner's account.


I would prefer the example before the detailed flow, as it helps to picture better the flow

Why here the debt is $4000?

Sorry, I didnt clarify here the starting case is same as where the open position wrapper left off. 5 ETH at $1000 is around $5000 of debt, so starting with $6000 of debt, you end up with $1000 left over. added some clarification.

fedgiac

I've read the overview so far and I like it. I think it gives the right amount of context. Will be reading 02 to 05 tomorrow.

fedgiac · 2026-02-16T18:32:07Z

+
+## Introduction
+
+This repository contains **Euler-CoW Protocol integration contracts** that enable leveraged position management (opening, closing, growing, and shrinking) and collateral swaps through CoW Protocol settlements combined with [Ethereum Vault Connector (EVC)](https://evc.wtf/) operations. The contracts, using CoW's [Generalized Wrappers](https://docs.cow.fi/cow-protocol/concepts/order-types/wrappers) architecture, coordinate complex multi-step DeFi operations atomically around a CoW settlement operation. Through its


The link to generalized wrapper is broken, which makes sense since they are introduced in this repo as well. Since they're also audited, they should also be documented and they probably deserve their own page in the current docs structure.

ok makes sense. Will try and draft something up.

fedgiac · 2026-02-16T18:53:00Z

+
+### 1. CowEvcOpenPositionWrapper
+
+The [`CowEvcOpenPositionWrapper`](../../src/CowEvcOpenPositionWrapper.sol) opens or grows leveraged positions (long or short).


Maybe stupid question but what does long or short mean here?
In the example below, I'd say the position is short in ETH. It can arguably be said to be long in USDC but anyway, I'd think of this mainly as a short.

I'm even considering if we should call the OpenPosition wrapper a Short wrapper. (But then it isn't nicely symmetric with the next one, so maybe not.)

obviously I am not a trading expert. When I say "long x", it means that I am creating exposure to x such that as x price rises, I get money, and when "short x", I gain money when x price falls. Generally there is some "safe haven" collateral asset that is used , which is generally USD, which is why I suppose its kind of unusual to say you are "long USD" because if X's price falls, that doesn't necessarily mean that you gained money because USD went up.

I'm even considering if we should call the OpenPosition wrapper a Short wrapper. (But then it isn't nicely symmetric with the next one, so maybe not.)

I suppose it would make sense here to give examples of how it works both "long" and "short". The open position wrapper can also be a long wrapper. Consider if the user started with ETH and then borrowed USD, its wierd to say you are "short USD" because USD is not a volatile asset, so instead we just say you are long ETH. So whatever asset is used as collateral is always "long" and the collateral used as debt is always "short", but that doesn't make it a "short wrapper" I would say.

fedgiac · 2026-02-16T19:21:09Z

+
+## Security Model
+
+### Trusted Actor: Solvers


Nit, just because all the items in the list are unrelated to solvers.

Suggested change

### Trusted Actor: Solvers

### Trusted Components

the purpose of this section is intended to explain why solvers can be trusted (both by onchain and offchain processes). The examples given are specific onchain safeguards designed to prevent solvers from having incentive to steal funds, and the mentioning of slashing is explaining that solvers are constrained by that offchain. Seems reasonable to me?

Co-authored-by: Federico Giacon <58218759+fedgiac@users.noreply.github.com>

…integration-contracts into feat/add-docs

## Description We received feedback from the auditors. This PR contains commits to resolve any findings that they had. ## Out of Scope This is only covering changes to the code; any changes to the docs will be done as part of the #20 PR (separately committed, tbd) ## Testing Instructions Browse through the audit findings. I included commit hashes with every fix that was implemented. If anything seems amiss please feel free to comment either here (for specific feedback) or on the finding itself (for more general/overarching choices). --------- Co-authored-by: Federico Giacon <58218759+fedgiac@users.noreply.github.com>

anxolin reviewed Feb 11, 2026

View reviewed changes

fedgiac reviewed Feb 16, 2026

View reviewed changes

Base automatically changed from feat/collateral-swap-wrapper to master February 17, 2026 12:01

rebase

4538990

kaze-cow force-pushed the feat/add-docs branch from dc09157 to 4538990 Compare February 24, 2026 05:51

kaze-cow and others added 3 commits February 24, 2026 15:05

Update docs/01-overview.md

dbfb3bb

Co-authored-by: Federico Giacon <58218759+fedgiac@users.noreply.github.com>

responses from feedback

1d211b9

Merge branch 'feat/add-docs' of https://github.com/cowprotocol/euler-…

c2273b2

…integration-contracts into feat/add-docs

kaze-cow mentioned this pull request Mar 3, 2026

Respond to initial audit feedback #24

Merged

kaze-cow requested review from anxolin and fedgiac March 5, 2026 14:29

Merge branch 'master' into feat/add-docs

5f6bff7


		### Base Framework: CowWrapper

		`CowWrapper.sol` is a self-contained abstract base contract provided by the CoW DAO which should be used for all wrappers. In particular it ensures:


		### EVC Integration Base: CowEvcBaseWrapper

		`CowEvcBaseWrapper.sol` extends `CowWrapper` with:


		Result: User's debt is repaid and remaining collateral is returned

		Example: User closes a 5 ETH short position (ETH = $1000). Around 5000 USDC collateral is swapped to exactly the user's debt of 5 ETH. The debt is repaid, and remaining USDC ($1000) is returned to the owner's account.


		## Introduction

		This repository contains Euler-CoW Protocol integration contracts that enable leveraged position management (opening, closing, growing, and shrinking) and collateral swaps through CoW Protocol settlements combined with [Ethereum Vault Connector (EVC)](https://evc.wtf/) operations. The contracts, using CoW's [Generalized Wrappers](https://docs.cow.fi/cow-protocol/concepts/order-types/wrappers) architecture, coordinate complex multi-step DeFi operations atomically around a CoW settlement operation. Through its


		### 1. CowEvcOpenPositionWrapper

		The [`CowEvcOpenPositionWrapper`](../../src/CowEvcOpenPositionWrapper.sol) opens or grows leveraged positions (long or short).

Uh oh!

Conversation

kaze-cow commented Feb 11, 2026

Description

Context

Testing Instructions

Uh oh!

anxolin left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

fedgiac left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants