docs: add comprehensive generalized wrappers documentation

docs/cow-protocol/concepts/order-types/wrappers.md

@@ -0,0 +1,91 @@
+---
+sidebar_position: 7
+---
+
+# Generalized Wrappers
+
+Generalized wrappers is a new framework to allow custom logic to execute before and/or after order settlement on CoW Protocol. They enable complex DeFi workflows—like flash loans, leveraged positions, and programmatic orders—all while preserving the security and assurances granted by CoW Protocol.
+
+## What are Wrappers?
+
+Wrappers are smart contracts that "wrap" the settlement process, executing custom logic surrounding settlement contract. When a solver executes a settlement that includes a wrapper, they call the wrapper contract instead of the settlement contract directly. The wrapper calls the settlement contract on behalf of the solver.
+
+This mechanism extends CoW Protocol's functionality in a modular way, allowing new features and integrations to be added without modifying the core settlement contract or requiring any changes to solver implementations.
+
+## Use Cases
+
+Wrappers enable a wide variety of advanced trading and DeFi operations:
+
+### Leverage Positions
+
+By wrapping the execution context of a CoW settlement, protocols implementing leveraged position opening capabilities can be supported.
+
+As the flagship GW implementation, Euler demonstrates a quintessential implementation of this use case. The wrapper:
+
+1. Coordinates with Euler's Ethereum Vault Connector (EVC) batch execution system
+2. Executes the necessary EVC batch operations before settlement
+3. Performs the settlement to acquire the leveraged asset
+4. Completes the position setup after settlement
+
+This enables users to open leveraged positions on Euler through a single CoW Protocol order, with all the complexity handled by the wrapper. Leveraged positions are associated with high-volume trading, so CoW benefits from increased revenue from such integrations.
+
+### Flash Loan Integration
+
+Currently, CoW Protocol uses a dedicated `FlashLoanRouter` contract for flash loan functionality. However, this implementation comes with additional implementation effort from both the solvers and the CoW Protocol backend infrastructure. With generalized wrappers, flash loan integration becomes simpler and more flexible.
+
+### Programmatic Orders
+
+By introducing a wrapped order type combined with [composable-cow](../../reference/contracts/periphery/composable_cow.md) conditional order generators, it is possible for any account (EOA or smart contract wallet) to authorize delayed orders that can be triggered at a specified time. The wrapper contract provides the signing authentication, the conditional order contract controls the logic for when the order can execute, and the CoW Settlement contract protects the execution of the swap generated by the conditional order.
+
+### Protocol-Approved Hooks
+
+Unlike [CoW Hooks](./cow-hooks.mdx), which can revert even if the order is executed successfully, wrappers provide a way to enforce required pre- and post-settlement operations. Since wrappers are protocol-approved through the allowlist authenticator, they can implement critical functionality that must execute:
+
+- Compliance checks (e.g., OFAC screening)
+- Cross chain transfers (pre- or post- transfer)
+- Deposit in a vault or other wrapper contract (swap and stake)
+
+The key difference from hooks is that if a wrapper is required for an order, the settlement cannot proceed without it—making wrappers ideal for transactions requiring robust execution.
+
+## Considerations
+
+While wrappers are powerful, there are important considerations to keep in mind:
+
+### Gas Overhead
+
+Wrappers add gas overhead to settlement transactions. Benchmarks show that even an empty wrapper (one that does nothing but pass through to settlement) adds approximately 22,272 gas, or about 11.4% overhead. The actual overhead depends on:
+
+- The complexity of the wrapper's logic
+- The size of the settlement data being passed through
+- The number of nested wrappers in the chain
+
+For many use cases, this overhead is acceptable given the functionality unlocked, but it's an important factor in deciding whether to use a wrapper.
+
+### Requires Protocol Approval
+
+Wrappers cannot be deployed and used immediately—they must be approved by CoW DAO through the allowlist authenticator. This approval process ensures high-quality wrapper implementations and safety for solvers, but means there's a roadblock for developers looking to extend CoW Protocol. Developers should plan for this approval process when building wrapper-based integrations.
+
+### On-Chain Protocol Does Not Enforce Execution
+
+Despite official rules enforcing the execution of wrappers when required by the user, a solver may choose not to execute a wrapper with an order. This means wrappers must be designed defensively:
+
+- If a wrapper is strictly required, the order should fail to settle without it
+- Wrappers should validate all input data and fail in cases where a user's funds could be at risk
+
+### Encoding Complexity
+
+To improve gas performance, wrapper data is encoded in a condensed format. Constructing wrapper calldata correctly can be complex, especially when nesting multiple wrappers. While the protocol provides helper contracts like `CowWrapperHelper` to simplify this, developers need to understand the encoding scheme to build robust integrations.
+
+## Getting Started
+
+Wrappers are a powerful tool for advanced integrations on CoW Protocol. To start building with wrappers:
+
+- **For developers**: See the [Integration Guide](../../integrate/wrappers.mdx) for implementation details, code examples, and security guidelines
+- **For technical specs**: Consult the [Technical Reference](../../reference/contracts/periphery/wrapper.mdx) for detailed contract documentation and API specifications
+
+To learn more about wrappers and see example implementations:
+
+- [Euler Integration Contracts Repository](https://github.com/cowprotocol/euler-integration-contracts) - Contains the `CowWrapper` abstract contract and example implementations
+- [Services Repository PR #3700](https://github.com/cowprotocol/services/pull/3700) - Backend integration implementation. Good reference for solvers looking to support wrappers.
+
+Wrappers represent a significant evolution in CoW Protocol's capabilities, enabling complex DeFi workflows while maintaining security and simplicity for solvers. As more wrappers are developed and approved, they will continue to expand what's possible with intent-based trading.