cowprotocol-orderbook 0.1.0

//! Order wire bodies: `OrderCreation`, the `POST /api/v1/orders` body
//! and its serde wire shape (carrying the owner's signature, the
//! canonical app-data JSON and the same amounts that were hashed for
//! EIP-712 signing), plus [`Order`] and [`OrderStatus`], the
//! `GET /api/v1/orders/{uid}` response model.

use alloy_primitives::{Address, Bytes, U256};
use serde::{Deserialize, Serialize};
use serde_with::{DisplayFromStr, serde_as};

use crate::{
    app_data::AppDataHash,
    error::{Error, Result},
    order::{BuyTokenDestination, OrderClass, OrderData, OrderKind, OrderUid, SellTokenSource},
    signature::Signature,
    signing_scheme::SigningScheme,
};

/// Server-side lifecycle status from `GET /api/v1/orders/{uid}`.
#[derive(Clone, Copy, Debug, Default, Deserialize, Eq, Hash, PartialEq, Serialize)]
#[serde(rename_all = "camelCase")]
pub enum OrderStatus {
    /// Awaiting on-chain pre-signature.
    PresignaturePending,
    /// Live; waiting for a solver to settle.
    #[default]
    Open,
    /// Fully matched on-chain.
    Fulfilled,
    /// Off-chain delete or on-chain pre-sign reversal.
    Cancelled,
    /// `validTo` passed before any fill.
    Expired,
}

/// Full order returned by `GET /api/v1/orders/{uid}`. Flattens the
/// 12 [`OrderData`] fields plus server-derived metadata; less-common
/// contextual objects stay as opaque JSON for forward-compat.
#[serde_as]
#[derive(Clone, Debug, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct Order {
    /// The 12 signed fields ([`OrderData`]).
    #[serde(flatten)]
    pub data: OrderData,
    /// 56-byte order UID against the chain's settlement domain.
    pub uid: OrderUid,
    /// Owner that signed the order.
    pub owner: Address,
    /// Signing scheme used by the owner.
    pub signing_scheme: SigningScheme,
    /// Raw signature bytes, hex-encoded.
    pub signature: String,
    /// ISO-8601 timestamp the orderbook accepted the order.
    pub creation_date: String,
    /// Current server-side lifecycle status.
    pub status: OrderStatus,
    /// Server-side order classification.
    pub class: OrderClass,
    /// Cumulative buy-side fill, atomic units.
    #[serde_as(as = "DisplayFromStr")]
    pub executed_buy_amount: U256,
    /// Cumulative sell-side fill, atomic units.
    #[serde_as(as = "DisplayFromStr")]
    pub executed_sell_amount: U256,
    /// Executed fee in `executed_fee_token` atomic units.
    #[serde_as(as = "Option<DisplayFromStr>")]
    #[serde(default)]
    pub executed_fee: Option<U256>,
    /// Token used to charge `executed_fee`.
    #[serde(default)]
    pub executed_fee_token: Option<Address>,
    /// `true` once the order is invalidated (cancelled / replaced).
    #[serde(default)]
    pub invalidated: bool,
    /// `true` if classified as a liquidity order.
    #[serde(default)]
    pub is_liquidity_order: bool,
    /// Full app-data document, when the orderbook stored it.
    #[serde(default)]
    pub full_app_data: Option<String>,
    /// Quote that produced the order, when one was supplied.
    #[serde(default)]
    pub quote: Option<serde_json::Value>,
    /// Pre/post settlement interactions from app-data hooks.
    #[serde(default)]
    pub interactions: Option<serde_json::Value>,
    /// EthFlow metadata for native-sell orders.
    #[serde(default)]
    pub ethflow_data: Option<serde_json::Value>,
    /// On-chain placement metadata for EthFlow orders.
    #[serde(default)]
    pub onchain_order_data: Option<serde_json::Value>,
    /// On-chain user (distinct from `owner` for proxy/relayer flows).
    #[serde(default)]
    pub onchain_user: Option<Address>,
    /// Settlement contract that processed the trade, when known.
    #[serde(default)]
    pub settlement_contract: Option<Address>,
}

/// Body of `POST /api/v1/orders`.
///
/// Differs from a raw [`OrderData`] in three load-bearing ways
/// (`cow-protocol/howto/integrate/api.mdx`):
///
/// - `fee_amount` here is what the user signed (which must be `0`); the
///   protocol fee is taken from surplus at settlement.
/// - `app_data` is the canonical JSON string of the metadata document;
///   `app_data_hash` is the `keccak256` digest of those exact bytes. The
///   signed [`OrderData::app_data`] field equals `app_data_hash`.
/// - `signing_scheme`, `signature` and `from` carry the owner's signature
///   along with the order.
///
/// Use [`OrderCreation::from_signed_order_data`] to assemble the body once
/// the owner has signed [`crate::OrderQuoteResponse::try_to_order_data`].
#[serde_as]
#[derive(Clone, Debug, Deserialize, Serialize)]
#[serde(rename_all = "camelCase", try_from = "OrderCreationWire")]
pub struct OrderCreation {
    /// Token the owner is selling.
    pub sell_token: Address,
    /// Token the owner is buying.
    pub buy_token: Address,
    /// Optional buy-token recipient.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub receiver: Option<Address>,
    /// Sell amount in atomic units (must agree with the signed payload).
    #[serde_as(as = "DisplayFromStr")]
    pub sell_amount: U256,
    /// Buy amount in atomic units (must agree with the signed payload).
    #[serde_as(as = "DisplayFromStr")]
    pub buy_amount: U256,
    /// Order expiry in Unix seconds.
    pub valid_to: u32,
    /// Canonical JSON of the app-data document.
    pub app_data: String,
    /// `keccak256(app_data)`. Mirrors the signed payload's `app_data` field.
    pub app_data_hash: AppDataHash,
    /// User-signed fee amount. Must be `"0"` at submission.
    #[serde_as(as = "DisplayFromStr")]
    pub fee_amount: U256,
    /// Direction of the order.
    pub kind: OrderKind,
    /// Whether partial fills are allowed.
    pub partially_fillable: bool,
    /// Source the sell amount is drawn from.
    pub sell_token_balance: SellTokenSource,
    /// Destination the buy amount is paid to.
    pub buy_token_balance: BuyTokenDestination,
    /// Off-chain signing scheme used to authenticate the order.
    pub signing_scheme: SigningScheme,
    /// Signature bytes. Empty for [`SigningScheme::PreSign`].
    #[serde(serialize_with = "serialise_signature_bytes")]
    pub signature: Signature,
    /// Order owner. Required for `presign` / `eip1271`; recommended for
    /// ECDSA schemes so the server can reject malformed signatures early.
    pub from: Address,
    /// Identifier returned by `POST /api/v1/quote`. Optional but improves
    /// solver fee accounting when the order is matched.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub quote_id: Option<i64>,
}

fn serialise_signature_bytes<S>(
    signature: &Signature,
    serializer: S,
) -> std::result::Result<S::Ok, S::Error>
where
    S: serde::Serializer,
{
    Bytes::from(signature.to_bytes()).serialize(serializer)
}

/// Deserialisation helper for [`OrderCreation`].
///
/// The wire format flattens `signature` to a hex string while
/// `signing_scheme` lives in a sibling field. Serde's per-field
/// `deserialize_with` cannot see siblings, so we shape the JSON into
/// this `Wire` form first (with `signature` as raw bytes) and then
/// reassemble the typed [`Signature`] enum in [`TryFrom`] using
/// [`Signature::from_bytes`].
#[serde_as]
#[derive(Deserialize)]
#[serde(rename_all = "camelCase")]
struct OrderCreationWire {
    sell_token: Address,
    buy_token: Address,
    #[serde(default)]
    receiver: Option<Address>,
    #[serde_as(as = "DisplayFromStr")]
    sell_amount: U256,
    #[serde_as(as = "DisplayFromStr")]
    buy_amount: U256,
    valid_to: u32,
    app_data: String,
    app_data_hash: AppDataHash,
    #[serde_as(as = "DisplayFromStr")]
    fee_amount: U256,
    kind: OrderKind,
    partially_fillable: bool,
    sell_token_balance: SellTokenSource,
    buy_token_balance: BuyTokenDestination,
    signing_scheme: SigningScheme,
    signature: Bytes,
    from: Address,
    #[serde(default)]
    quote_id: Option<i64>,
}

impl TryFrom<OrderCreationWire> for OrderCreation {
    type Error = crate::error::Error;

    /// Reassemble an [`OrderCreation`] from its wire form, applying the
    /// same invariants [`OrderCreation::from_signed_order_data`] enforces
    /// on the construction path: the signature payload must parse for the
    /// declared scheme, `from` must be non-zero, and
    /// `keccak256(app_data) == app_data_hash`. Without the digest check, a
    /// hostile orderbook (or any intermediary) could hand the SDK a body
    /// whose JSON document disagrees with the hash the user signed.
    fn try_from(wire: OrderCreationWire) -> std::result::Result<Self, Self::Error> {
        let signature = Signature::from_bytes(wire.signing_scheme, &wire.signature)?;
        let order_data = OrderData {
            sell_token: wire.sell_token,
            buy_token: wire.buy_token,
            receiver: wire.receiver,
            sell_amount: wire.sell_amount,
            buy_amount: wire.buy_amount,
            valid_to: wire.valid_to,
            app_data: wire.app_data_hash,
            fee_amount: wire.fee_amount,
            kind: wire.kind,
            partially_fillable: wire.partially_fillable,
            sell_token_balance: wire.sell_token_balance,
            buy_token_balance: wire.buy_token_balance,
        };
        Self::from_signed_order_data(
            &order_data,
            signature,
            wire.from,
            wire.app_data,
            wire.quote_id,
        )
    }
}

impl OrderCreation {
    /// Project the 12 signed fields back out of an [`OrderCreation`] as
    /// the [`OrderData`] the EIP-712 hash and UID were computed against.
    /// Useful for re-hashing the order during owner verification.
    pub const fn order_data(&self) -> OrderData {
        OrderData {
            sell_token: self.sell_token,
            buy_token: self.buy_token,
            receiver: self.receiver,
            sell_amount: self.sell_amount,
            buy_amount: self.buy_amount,
            valid_to: self.valid_to,
            app_data: self.app_data_hash,
            fee_amount: self.fee_amount,
            kind: self.kind,
            partially_fillable: self.partially_fillable,
            sell_token_balance: self.sell_token_balance,
            buy_token_balance: self.buy_token_balance,
        }
    }

    /// Recover the signer of this order from its embedded signature and
    /// assert it matches `self.from`. Returns `self.from` on success.
    ///
    /// - [`SigningScheme::Eip712`] and [`SigningScheme::EthSign`]:
    ///   recovers via ECDSA and compares against `self.from`.
    /// - [`SigningScheme::Eip1271`] and [`SigningScheme::PreSign`]:
    ///   the signature does not carry a recoverable owner; the call
    ///   short-circuits to `Ok(self.from)` because the orderbook (or
    ///   `GPv2Signing.setPreSignature`) will validate the owner
    ///   on-chain. Callers that need to verify the EIP-1271 path
    ///   pre-submission must call the contract's `isValidSignature`
    ///   themselves.
    ///
    /// Recommended belt-and-suspenders call site:
    /// `creation.verify_owner(&settlement_domain(chain.id(), chain.settlement()))?;`
    /// before `OrderBookApi::post_order` to catch signing-key /
    /// `from`-address divergence client-side.
    pub fn verify_owner(
        &self,
        domain: &crate::domain::DomainSeparator,
    ) -> std::result::Result<Address, crate::signature::SignatureError> {
        let payload = crate::order::eip712::Order::from(&self.order_data());
        match self.signature.recover(domain, &payload)? {
            Some(recovered) if recovered.signer == self.from => Ok(self.from),
            Some(recovered) => Err(crate::signature::SignatureError::SignerMismatch {
                declared: self.from,
                recovered: recovered.signer,
            }),
            // EIP-1271 / PreSign: the signature does not carry a
            // recoverable owner, but a synthesised `OrderCreation` (e.g.
            // round-tripped through JSON) could still set `from = ZERO`.
            // Reject that case explicitly so callers do not treat the
            // `Ok` arm as a positive owner assertion. The orderbook (or
            // `GPv2Signing.setPreSignature`) still validates the owner
            // on-chain in the non-zero case.
            None if self.from == Address::ZERO => {
                Err(crate::signature::SignatureError::SignerMismatch {
                    declared: Address::ZERO,
                    recovered: Address::ZERO,
                })
            }
            None => Ok(self.from),
        }
    }

    /// Assemble a submission body from a signed [`OrderData`] plus the
    /// metadata required by the orderbook (`from`, signature, app-data
    /// document, optional quote id).
    ///
    /// Validates that `from` is non-zero (the orderbook rejects every
    /// scheme with `from = Address::ZERO`, and the contract-signed schemes
    /// `Eip1271` / `PreSign` carry the owner explicitly there). Callers
    /// who want to additionally cross-check that `from` matches the
    /// recovered signer of an ECDSA signature can call
    /// [`OrderCreation::verify_owner`] on the assembled body.
    pub fn from_signed_order_data(
        order_data: &OrderData,
        signature: Signature,
        from: Address,
        app_data_json: String,
        quote_id: Option<i64>,
    ) -> Result<Self> {
        if from == Address::ZERO {
            return Err(Error::OrderCreationInvalid {
                field: "from",
                reason: "owner address must be non-zero",
            });
        }
        // The JSON document MUST hash to the digest the order was signed
        // against. Otherwise a wrapper layer can bind the user's
        // signature to bytes the orderbook never sees, while pinning a
        // different document under the same hash via `put_app_data`.
        let json_digest = alloy_primitives::keccak256(app_data_json.as_bytes());
        if json_digest != order_data.app_data {
            return Err(Error::OrderCreationInvalid {
                field: "app_data",
                reason: "JSON digest does not match signed app_data hash",
            });
        }
        // `Some(Address::ZERO)` and `None` mean the same thing (use owner)
        // but cow-sdk and cow-py emit `None` on the wire. Normalise so the
        // wire payload, signed hash and contract decoding always agree.
        let receiver = match order_data.receiver {
            Some(addr) if addr == Address::ZERO => None,
            other => other,
        };
        Ok(Self {
            sell_token: order_data.sell_token,
            buy_token: order_data.buy_token,
            receiver,
            sell_amount: order_data.sell_amount,
            buy_amount: order_data.buy_amount,
            valid_to: order_data.valid_to,
            app_data: app_data_json,
            app_data_hash: order_data.app_data,
            fee_amount: order_data.fee_amount,
            kind: order_data.kind,
            partially_fillable: order_data.partially_fillable,
            sell_token_balance: order_data.sell_token_balance,
            buy_token_balance: order_data.buy_token_balance,
            signing_scheme: signature.scheme(),
            signature,
            from,
            quote_id,
        })
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::app_data::{EMPTY_APP_DATA_HASH, EMPTY_APP_DATA_JSON};
    use crate::domain::{DomainSeparator, settlement_domain};
    use crate::signing_scheme::EcdsaSigningScheme;
    use alloy_primitives::address;
    use alloy_signer_local::PrivateKeySigner;

    const SETTLEMENT: Address = address!("9008D19f58AAbD9eD0D60971565AA8510560ab41");

    /// All-zero EIP-712 placeholder signature for wire-shape tests. Not
    /// recoverable; never pass it to recovery paths.
    fn zero_eip712_signature() -> Signature {
        Signature::Eip712(crate::signature::EcdsaSignature::from_bytes_and_parity(
            &[0u8; 64], false,
        ))
    }

    /// `OrderData` whose `app_data` is `EMPTY_APP_DATA_HASH`, so the
    /// canonical `EMPTY_APP_DATA_JSON` document hashes to match it.
    fn empty_app_data_order() -> OrderData {
        OrderData {
            sell_token: address!("aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"),
            buy_token: address!("bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"),
            receiver: None,
            sell_amount: U256::from(1_000_000u64),
            buy_amount: U256::from(999u64),
            valid_to: 0xffff_ffff,
            app_data: EMPTY_APP_DATA_HASH,
            fee_amount: U256::ZERO,
            kind: OrderKind::Sell,
            partially_fillable: false,
            sell_token_balance: SellTokenSource::default(),
            buy_token_balance: BuyTokenDestination::default(),
        }
    }

    fn signer() -> PrivateKeySigner {
        PrivateKeySigner::from_bytes(&U256::from(1u64).to_be_bytes().into()).unwrap()
    }

    /// `from_signed_order_data` rejects a zero `from` address locally
    /// rather than letting the orderbook reject it.
    #[test]
    fn from_signed_order_data_rejects_zero_from_address() {
        let err = OrderCreation::from_signed_order_data(
            &OrderData::default(),
            zero_eip712_signature(),
            Address::ZERO,
            EMPTY_APP_DATA_JSON.to_owned(),
            None,
        )
        .unwrap_err();
        assert!(
            matches!(err, Error::OrderCreationInvalid { field: "from", .. }),
            "got: {err}"
        );
    }

    /// R21: `from_signed_order_data` rejects an `app_data` JSON document
    /// whose keccak256 does not match the `OrderData::app_data` digest the
    /// user signed against.
    #[test]
    fn from_signed_order_data_rejects_app_data_digest_mismatch() {
        let err = OrderCreation::from_signed_order_data(
            &empty_app_data_order(),
            zero_eip712_signature(),
            address!("70997970C51812dc3A010C7d01b50e0d17dc79C8"),
            // Document does NOT hash to `EMPTY_APP_DATA_HASH`.
            r#"{"version":"1.6.0","metadata":{}}"#.to_owned(),
            None,
        )
        .unwrap_err();
        assert!(
            matches!(
                err,
                Error::OrderCreationInvalid {
                    field: "app_data",
                    ..
                }
            ),
            "got: {err}"
        );
    }

    /// R21b: the `TryFrom<OrderCreationWire>` deserialisation path applies
    /// the same digest check. Serialise a valid body, swap the `appData`
    /// document for one whose keccak256 differs while leaving `appDataHash`
    /// untouched, and confirm `serde_json` rejects it before the body can
    /// be relayed downstream.
    #[test]
    fn deserialise_rejects_app_data_digest_mismatch() {
        let creation = OrderCreation::from_signed_order_data(
            &empty_app_data_order(),
            zero_eip712_signature(),
            address!("70997970C51812dc3A010C7d01b50e0d17dc79C8"),
            EMPTY_APP_DATA_JSON.to_owned(),
            None,
        )
        .unwrap();
        let mut body = serde_json::to_value(creation).unwrap();
        body["appData"] = serde_json::Value::String(r#"{"version":"1.6.0","metadata":{}}"#.into());
        let err = serde_json::from_value::<OrderCreation>(body).unwrap_err();
        assert!(
            err.to_string().contains("app_data"),
            "expected app_data digest mismatch surfaced through serde, got: {err}"
        );
    }

    /// R22: `verify_owner` rejects a synthesised EIP-1271 / PreSign body
    /// whose `from` is the zero address. The `Ok` arm must never act as a
    /// positive owner assertion for an obviously bogus body.
    #[test]
    fn verify_owner_rejects_zero_from_for_onchain_schemes() {
        // Build the OrderCreation directly, bypassing
        // `from_signed_order_data` (which already rejects zero-from), so we
        // reproduce the wire shape an attacker could synthesise.
        let creation = OrderCreation {
            sell_token: Address::ZERO,
            buy_token: Address::ZERO,
            receiver: None,
            sell_amount: U256::ZERO,
            buy_amount: U256::ZERO,
            valid_to: 0,
            app_data: EMPTY_APP_DATA_JSON.to_owned(),
            app_data_hash: EMPTY_APP_DATA_HASH,
            fee_amount: U256::ZERO,
            kind: OrderKind::Sell,
            partially_fillable: false,
            sell_token_balance: SellTokenSource::default(),
            buy_token_balance: BuyTokenDestination::default(),
            signing_scheme: SigningScheme::PreSign,
            signature: Signature::PreSign,
            from: Address::ZERO,
            quote_id: None,
        };
        let err = creation
            .verify_owner(&DomainSeparator::default())
            .unwrap_err();
        assert!(matches!(
            err,
            crate::signature::SignatureError::SignerMismatch { .. }
        ));
    }

    /// R23: `verify_owner` rejects an ECDSA-signed body whose declared
    /// `from` is not the address recovered from the signature. The
    /// typo-and-wallet-switch case the WASM `build_order_creation` shim
    /// relies on to fail fast client-side instead of pushing the bad pair
    /// to the orderbook.
    #[test]
    fn verify_owner_rejects_signer_mismatch_for_ecdsa() {
        let signer = signer();
        let real_signer = signer.address();
        let impostor = address!("dead0000dead0000dead0000dead0000dead0000");
        assert_ne!(real_signer, impostor);

        let domain = settlement_domain(1, SETTLEMENT);
        let order_data = empty_app_data_order();
        let signature = order_data
            .sign(EcdsaSigningScheme::Eip712, &domain, &signer)
            .unwrap();
        // Build the body with the *wrong* declared owner.
        let creation = OrderCreation::from_signed_order_data(
            &order_data,
            signature,
            impostor,
            EMPTY_APP_DATA_JSON.to_owned(),
            None,
        )
        .unwrap();
        let err = creation.verify_owner(&domain).unwrap_err();
        match err {
            crate::signature::SignatureError::SignerMismatch {
                declared,
                recovered,
            } => {
                assert_eq!(declared, impostor);
                assert_eq!(recovered, real_signer);
            }
            other => panic!("expected SignerMismatch, got {other:?}"),
        }
    }

    /// `verify_owner` returns the owner when the declared `from` matches the
    /// address recovered from a real ECDSA signature: the success path the
    /// mismatch test guards.
    #[test]
    fn verify_owner_succeeds_for_matching_ecdsa_signer() {
        let signer = signer();
        let owner = signer.address();
        let domain = settlement_domain(1, SETTLEMENT);
        let order_data = empty_app_data_order();
        let signature = order_data
            .sign(EcdsaSigningScheme::Eip712, &domain, &signer)
            .unwrap();
        let creation = OrderCreation::from_signed_order_data(
            &order_data,
            signature,
            owner,
            EMPTY_APP_DATA_JSON.to_owned(),
            None,
        )
        .unwrap();
        assert_eq!(creation.verify_owner(&domain).unwrap(), owner);
    }
}