feat: clearing library

Cargo.toml

@@ -90,6 +90,7 @@ valence-ica-cctp-transfer            = { path = "contracts/libraries/ica-cctp-tr
 valence-ica-ibc-transfer             = { path = "contracts/libraries/ica-ibc-transfer", features = ["library"] }
 valence-supervaults-lper             = { path = "contracts/libraries/supervaults-lper", features = ["library"] }
 valence-supervaults-withdrawer       = { path = "contracts/libraries/supervaults-withdrawer", features = ["library"] }
+valence-clearing-queue               = { path = "contracts/libraries/clearing-queue", features = ["library"] }
 
 # middleware
 valence-middleware-osmosis = { path = "contracts/middleware/type-registries/osmosis/osmo-26-0-0", features = [

contracts/libraries/clearing-queue/.cargo/config.toml

@@ -0,0 +1,3 @@
+[alias]
+wasm   = "build --release --lib --target wasm32-unknown-unknown"
+schema = "run --bin schema"

contracts/libraries/clearing-queue/Cargo.toml

@@ -0,0 +1,30 @@
+[package]
+name       = "valence-clearing-queue"
+authors    = { workspace = true }
+edition    = { workspace = true }
+license    = { workspace = true }
+version    = { workspace = true }
+repository = { workspace = true }
+
+[lib]
+crate-type = ["cdylib", "rlib"]
+
+[features]
+# use library feature to disable all instantiate/execute/query exports
+library = []
+
+[dependencies]
+cosmwasm-schema         = { workspace = true }
+cosmwasm-std            = { workspace = true }
+cw-ownable              = { workspace = true }
+cw-storage-plus         = { workspace = true }
+cw-utils                = { workspace = true }
+valence-macros          = { workspace = true }
+valence-library-utils   = { workspace = true }
+valence-library-base    = { workspace = true }
+valence-processor-utils = { workspace = true }
+
+[dev-dependencies]
+cw-multi-test         = { workspace = true }
+valence-account-utils = { workspace = true }
+valence-library-utils = { workspace = true, features = ["testing"] }

contracts/libraries/clearing-queue/README.md

@@ -0,0 +1,36 @@
+# Valence Clearing Queue Library
+
+The **Valence Clearing Queue** library allows **registration and settlement of withdrawal obligations** in a FIFO (First-In-First-Out) manner. It maintains a queue of pending withdrawal obligations, with each obligation containing recipient information, payout amounts, and a unique identifier. When settling obligations, funds are pulled from a **settlement input account** and sent to the specified recipients.
+
+## High-level flow
+
+```mermaid
+---
+title: Clearing Queue Library
+---
+graph LR
+  IA((Settlement<br>Account))
+  R((Recipient))
+  P[Processor]
+  CQ[Clearing<br>Queue<br>Library]
+  P -- 1/Register<br>Obligation --> CQ
+  CQ -- 2/Store<br>Obligation --> CQ
+  P -- 3/Settle<br>Next<br>Obligation --> CQ
+  CQ -- 4/Query Settlement<br>Account Balance --> IA
+  CQ -- 5/Validate & Execute Transfer --> IA
+  IA -- 6/Send Funds --> R
+```
+
+## Configuration
+
+The library is configured on instantiation via the `LibraryConfig` type.
+
+```rust
+pub struct LibraryConfig {
+    /// settlement input account which we tap into in order
+    /// to settle the obligations
+    pub settlement_acc_addr: LibraryAccountType,
+}
+```
+
+The `settlement_acc_addr` specifies the account from which funds will be pulled to fulfill settlement obligations. The library will check that this account has sufficient balance before attempting to settle each obligation.