Crate cow_sdk_core

Expand description

§cow-sdk-core

Shared CoW Protocol core types and runtime-neutral trait contracts.

⚠️ Alpha — 0.1.0-alpha. Pre-release and not security-audited; the public API may change before 0.1.0. It is published as a pre-release, so Cargo selects it only when you opt in (cow-sdk-core = "0.1.0-alpha.10"). Review it yourself before relying on it with real funds.

cow-sdk-core is the foundation of the cow-rs crate family: the shared vocabulary and runtime-neutral seams every other crate is built on. It ships validated primitive types, environment and chain configuration, a uniform error taxonomy, and the trait shapes used across the workspace. It performs no protocol work of its own — it defines the types and boundaries the rest of the SDK fills in. Most consumers reach these types through the top-level cow-sdk facade re-exports; depend on this crate directly when you are building a sibling leaf crate or implementing a custom Signer, Provider, or HttpTransport adapter.

The cow-named identity and numeric primitive types ship as cow-owned #[repr(transparent)] newtypes over alloy_primitives per ADR 0052.

§What it provides

Identity & numeric newtypes — Address, Hash32, AppDataHash, HexData, OrderUid, OrderData, OrderKind, Amount/Amounts, TokenInfo, and the validity-window types, as cow-owned transparent newtypes over alloy_primitives.
The address! macro — compile-time-validated address literals. The literal must be the lowercase wire form; a mixed-case literal fails the build, because an EIP-55 checksum cannot be verified in const evaluation. A malformed address never reaches runtime.
Runtime-neutral trait seams — Signer, DigestSigner, TypedDataSigner, Provider, SigningProvider, LogProvider, and the object-safe HttpTransport, plus UserRejection, the bound that lets the SDK tell a user-declined signature apart from other signer failures. async_trait is re-exported for implementors.
Explicit transaction lifecycle states — TransactionBroadcast is the signer-side broadcast acknowledgement; TransactionReceipt is the provider-side mined observation with optional status, block, gas, sender, and recipient fields.
Chain & endpoint configuration — SupportedChainId, default API base URLs, canonical orderbook/subgraph host allow-lists, NATIVE_CURRENCY_ADDRESS, wrapped_native_token, ProtocolOptions, and ExternalHostPolicy for SSRF-resistant URL validation.
Uniform error taxonomy — ErrorClass, the coarse telemetry bucket every crate’s error maps to, alongside CoreError, ValidationError, and TransportErrorClass.
Secret redaction — Redacted<T> and the redacted URL-map types, so secret-bearing configuration never leaks through Debug, Display, or serde.
Cooperative cancellation — a re-exported CancellationToken plus the Cancellable / WithCancellation combinators for long-running SDK futures.
The HTTP transport seam — the HttpTransport async injection point with the native ReqwestTransport default (size-capped, URL-stripping on error) and its wasm32 sibling FetchTransport (the browser fetch default), both selected automatically by target.

§Install

[dependencies]
cow-sdk-core = "0.1.0-alpha.10"

§Minimal example

use cow_sdk_core::{Amount, SupportedChainId, wrapped_native_token};

// `Amount` is the typed atomic-quantity boundary. `from_units` builds a
// whole token amount from a number (no string, no zero-counting); reach for
// `parse_units` when the amount is fractional or arrives as text. Both scale
// by `10^decimals` with exact integer arithmetic, and `format_units` is the
// inverse for display.
let one_weth = Amount::from_units(1, 18)?;
assert_eq!(one_weth.to_string(), "1000000000000000000");
assert_eq!(one_weth.format_units(18), "1.000000000000000000");

// Fractional or user-supplied amounts arrive as a decimal string.
let one_and_a_half_weth = Amount::parse_units("1.5", 18)?;
assert_eq!(one_and_a_half_weth.to_string(), "1500000000000000000");

// A chain id drives real configuration: the API path segment used in
// orderbook base URLs, and the wrapped-native token metadata.
let chain = SupportedChainId::Mainnet;
assert_eq!(chain.api_path(), "mainnet");

let weth = wrapped_native_token(chain);
assert_eq!(weth.symbol, "WETH");
assert_eq!(weth.decimals, 18);

§Feature flags

Feature	Default	Enables
`transport-policy`	off	Shared HTTP retry, rate-limit, `Retry-After`, jitter, and transport-error classification policy used by the orderbook, subgraph, and IPFS clients. Off by default so a consumer that needs only the primitive types does not pull the retry-timer dependencies.
`tracing`	off	Emits `tracing` spans and events from the transport layer.

§Where this fits

This crate defines types and seams; it does not compute order hashes or signatures (see cow-sdk-signing), talk to the orderbook (see cow-sdk-orderbook), build or submit trades (see cow-sdk-trading), or decode contract events (see cow-sdk-contracts). The Signer and Provider seams are defined here; concrete native adapters live in cow-sdk-alloy-signer and cow-sdk-alloy-provider, and JavaScript and TypeScript hosts supply their own wallet across the cow-sdk-js callback boundary.

§Where to next

§License

Licensed under GPL-3.0-or-later. See the workspace LICENSE file for the full text. Shared CoW Protocol core types, validation helpers, configuration, and runtime-neutral traits used across the cow-sdk crate family.

Re-exports§

pub use cancellation::Cancellable;
pub use cancellation::Cancelled;
pub use cancellation::WithCancellation;
pub use config::AddressPerChain;
pub use config::ApiBaseUrls;
pub use config::ApiContext;
pub use config::CowEnv;
pub use config::DEFAULT_HTTP_TIMEOUT;
pub use config::DEFAULT_MAX_RESPONSE_BYTES;
pub use config::ExternalHostPolicy;
pub use config::HostPolicyError;
pub use config::HttpClientPolicy;
pub use config::MAX_VALID_TO_EPOCH;
pub use config::NATIVE_CURRENCY_ADDRESS;
pub use config::ProtocolOptions;
pub use config::SupportedChainId;
pub use config::UrlParseFailureClass;
pub use config::canonical_orderbook_hosts;
pub use config::canonical_subgraph_hosts;
pub use config::default_api_base_urls;
pub use config::validate_external_service_url;
pub use config::wrapped_native_token;
pub use errors::CoreError;
pub use errors::ErrorClass;
pub use errors::ValidationError;
pub use errors::serialization_error_category;
pub use redaction::REDACTED_PLACEHOLDER;
pub use redaction::REDACTED_RESPONSE_BODY_MAX_BYTES;
pub use redaction::RESPONSE_BODY_TRUNCATION_MARKER;
pub use redaction::Redacted;
pub use redaction::RedactedOptionalUrlMap;
pub use redaction::RedactedUrlMap;
pub use redaction::redact_response_body;
pub use traits::BlockInfo;
pub use traits::ContractCall;
pub use traits::DigestSigner;
pub use traits::LogProvider;
pub use traits::Provider;
pub use traits::Signer;
pub use traits::SigningProvider;
pub use traits::TransactionBroadcast;
pub use traits::TransactionReceipt;
pub use traits::TransactionRequest;
pub use traits::TransactionStatus;
pub use traits::TypedDataDomain;
pub use traits::TypedDataEnvelope;
pub use traits::TypedDataField;
pub use traits::TypedDataPayload;
pub use traits::TypedDataSigner;
pub use traits::TypedDataTypes;
pub use traits::UserRejection;
pub use transport::HttpTransport;
pub use transport::TransportError;
pub use transport::TransportResponse;
pub use transport::ReqwestTransport;Non-WebAssembly
pub use transport::ReqwestTransportConfig;Non-WebAssembly
pub use types::Address;
pub use types::Amount;
pub use types::Amounts;
pub use types::AppCode;
pub use types::AppCodeError;
pub use types::AppDataHash;
pub use types::BlockHash;
pub use types::BuyTokenDestination;
pub use types::ChainId;
pub use types::Costs;
pub use types::FeeComponent;
pub use types::Hash32;
pub use types::HexData;
pub use types::LogBlockSelector;
pub use types::LogMeta;
pub use types::LogQuery;
pub use types::NetworkFee;
pub use types::OrderData;
pub use types::OrderDigest;
pub use types::OrderKind;
pub use types::OrderUid;
pub use types::QuoteAmountsAndCosts;
pub use types::RawLog;
pub use types::SellTokenSource;
pub use types::TokenInfo;
pub use types::TransactionHash;
pub use types::ValidTo;
pub use validation::TransportErrorClass;
pub use validation::ValidationReason;

Modules§

cancellation: Canonical cancellation combinator for long-running SDK futures. Canonical cancellation combinator for long-running SDK futures.
config: Environment, address-book, and HTTP client policy types shared across crates. Environment, address-book, and HTTP client policy types shared across crates.
errors: Common validation and configuration errors used by the foundational crates.
redaction: Typed redaction wrapper for secret-bearing configuration fields. Redaction wrappers and response-body sanitization helpers for secret-bearing SDK surfaces.
traits: Runtime-neutral signer, provider, and typed-data trait contracts. Runtime-neutral signer, provider, and typed-data trait contracts.
transport: Async HTTP transport injection point and native reqwest default. HTTP transport injection point shared across cow-sdk crates.
types: Strongly typed user-domain values used across the SDK surface. Strongly typed user-domain values used across the SDK surface.
validation: Shared validation-failure and transport-classification enums. Shared validation-failure and transport-classification enums used across the cow-sdk crate family.

Macros§

address: Constructs a compile-time validated Address from a 0x-prefixed hexadecimal literal, mirroring alloy_primitives::address!.

Structs§

CancellationToken: Cooperative cancellation token propagated through SDK long-running operations.

Attribute Macros§

async_trait: The async_trait attribute macro, re-exported for implementors of the object-safe HttpTransport seam.