Documentation nits

README.md

@@ -4,7 +4,7 @@ A permissionless protocol for onchain payments that mimics traditional "authoriz
 
 ## Quick Start
 
-The Commerce Payments Protocol facilitates secure escrow-based payments with flexible authorization and capture patterns. Operators drive payment flows using modular token collectors while the protocol ensures buyer and merchant protections.
+The Commerce Payments Protocol facilitates secure escrow-based payments with flexible authorization and capture patterns. Operators drive payment flows using modular token collectors while the protocol ensures payer and merchant protections.
 
 **📖 [Read the Full Documentation](docs/README.md)**
 
@@ -22,12 +22,12 @@ The Commerce Payments Protocol facilitates secure escrow-based payments with fle
 
 | Contract | Address |
 |----------|---------|
-| AuthCaptureEscrow | `0xBdEA0D1bcC5966192B070Fdf62aB4EF5b4420cff` |
-| ERC3009PaymentCollector | `0x0E3dF9510de65469C4518D7843919c0b8C7A7757` |
-| Permit2PaymentCollector | `0x992476B9Ee81d52a5BdA0622C333938D0Af0aB26` |
-| PreApprovalPaymentCollector | `0x1b77ABd71FCD21fbe2398AE821Aa27D1E6B94bC6` |
-| SpendPermissionPaymentCollector | `0x8d9F34934dc9619e5DC3Df27D0A40b4A744E7eAa` |
-| OperatorRefundCollector | `0x934907bffd0901b6A21e398B9C53A4A38F02fa5d` |
+| AuthCaptureEscrow | [`0xBdEA0D1bcC5966192B070Fdf62aB4EF5b4420cff`](https://basescan.org/address/0xBdEA0D1bcC5966192B070Fdf62aB4EF5b4420cff#code) |
+| ERC3009PaymentCollector | [`0x0E3dF9510de65469C4518D7843919c0b8C7A7757`](https://basescan.org/address/0x0E3dF9510de65469C4518D7843919c0b8C7A7757#code) |
+| Permit2PaymentCollector | [`0x992476B9Ee81d52a5BdA0622C333938D0Af0aB26`](https://basescan.org/address/0x992476B9Ee81d52a5BdA0622C333938D0Af0aB26#code) |
+| PreApprovalPaymentCollector | [`0x1b77ABd71FCD21fbe2398AE821Aa27D1E6B94bC6`](https://basescan.org/address/0x1b77ABd71FCD21fbe2398AE821Aa27D1E6B94bC6#code) |
+| SpendPermissionPaymentCollector | [`0x8d9F34934dc9619e5DC3Df27D0A40b4A744E7eAa`](https://basescan.org/address/0x8d9F34934dc9619e5DC3Df27D0A40b4A744E7eAa#code) |
+| OperatorRefundCollector | [`0x934907bffd0901b6A21e398B9C53A4A38F02fa5d`](https://basescan.org/address/0x934907bffd0901b6A21e398B9C53A4A38F02fa5d#code) |
 
 ## Documentation
 
@@ -40,8 +40,8 @@ The Commerce Payments Protocol facilitates secure escrow-based payments with fle
   - [Capture](docs/operations/Capture.md) - Transfer authorized funds to merchants  
   - [Charge](docs/operations/Charge.md) - Immediate authorization and capture
   - [Void](docs/operations/Void.md) - Cancel authorizations (operator)
-  - [Reclaim](docs/operations/Reclaim.md) - Recover expired authorizations (buyer)
-  - [Refund](docs/operations/Refund.md) - Return captured funds to buyers
+  - [Reclaim](docs/operations/Reclaim.md) - Recover expired authorizations (payer)
+  - [Refund](docs/operations/Refund.md) - Return captured funds to payers
 
 ## Development
 

docs/Fees.md

@@ -57,7 +57,7 @@ When fees are applied:
 2. **Fee Transfer**: If `feeAmount > 0`, transfer to `feeReceiver`
 3. **Remaining Transfer**: Transfer `amount - feeAmount` to the merchant (`receiver`)
 
-## Comprehensive Examples
+## Examples
 
 ### Example 1: Fixed Fee Rate with Fixed Recipient
 

docs/README.md

@@ -1,21 +1,22 @@
 # Commerce Payments Protocol
 ## Overview
 
-The Commerce Payments Protocol facilitates onchain payments. Traditional payment flows typically involve a multi-step "authorize and capture" pattern where payments are initially placed on hold to guarantee payment for merchants at a later time. This payment lifecycle helps facilitate the management of race conditions that can occur between checkout completion, payment processing, and actual order fulfillment (for example, inventory selling out, tax burdens changing, gift card balances being spent, etc.). The Commerce Payments Protocol is a permissionless, immutable mechanism designed to securely facilitate the multi-step lifecycle of real-world payments onchain.
+Today, onchain payments work well for peer-to-peer transactions, but not for more complex commerce purchases, which require features like refunds, delayed capture, and tax finalization. For example, in commerce, merchants can run out of inventory and need to cancel a purchase, buyers can request refunds, orders may be completed in multiple deliveries, and more. The Commerce Payments Protocol enables onchain payments for commerce at scale by bridging this gap.
 
-Permissionless operators drive token movement through the protocol and can customize their operations with modular smart contracts. No top-level controls exist on the protocol, keeping it permissionless, immutable and usable by any operator. The permissionless nature of the core protocol prevents it from becoming a "walled garden" because anyone can act as an operator of the protocol and provide a layer of technical abstraction between merchants and the blockchain (including merchants themselves). Operators are trust-minimized and functionally restricted by the protocol, which tightly controls the flow of buyer and merchant funds and minimizes the potential for abuse by operators.
+Traditional finance’s solution is called "authorize and capture":
+- **Authorization** places hold on buyer funds
+- **Capture** distributes payment to the merchant
 
+This introduces an intermediary state of guaranteeing the ability to pay in the future without actually having finalized payment right now. Until now, onchain payments have been missing this capability.
 
-The protocol's core functionality revolves around two key concepts:
+The Commerce Payments Protocol brings Auth+Capture onchain through an Escrow smart contract. To authorize, funds move from buyer to Escrow, guaranteeing the ability to pay merchants. To capture, funds move from Escrow to merchant, finalizing payment. This simple 2-step process unlocks onchain payments for commerce at scale.
 
-- **Authorization**: A commitment of funds for a future payment. When authorized, funds are held in escrow but not yet transferred to the merchant. This is similar to a "hold" on a credit card.
-
-- **Capture**: Funds are transferred from escrow to merchants after fulfillment or other conditions ar met. Capture is guaranteed to succeed if funds have been authorized, providing merchants with payment certainty.
+To create a layer of abstraction between the payer or receiver of a given payment the need for direct interaction with the chain, the protocol is designed around the concept of a payment "operator". Operators drive payment movement through the Escrow, absorbing transaction fees and enabling background automations seamlessly.
 
+ No top-level controls exist on the protocol, keeping it permissionless, immutable and usable by any operator. The permissionless nature of the core protocol prevents it from becoming a "walled garden" because anyone can act as an operator of the protocol and provide a layer of technical abstraction between merchants and the blockchain (including merchants themselves). Operators are trust-minimized and cryptographically constrained by the protocol, which tightly controls the flow of payer and merchant funds and minimizes the potential for abuse by operators.
 
-This pattern ensures that successful authorization always leads to successful capture, providing merchants with payment guarantees while maintaining buyer protections.
 
-## Payment Lifecycle
+## Payment Operations
 
 The protocol provides six main functions that handle the complete payment lifecycle: `authorize`, `capture`, `charge`, `void`, `reclaim` and `refund`.
 
@@ -25,20 +26,20 @@ The protocol provides six main functions that handle the complete payment lifecy
 </div>
 
 ### Payment Initiation
-- **[Authorize](operations/Authorize.md)** - Reserve buyer funds in escrow for future capture. Enables delayed settlement while guaranteeing merchant payment upon successful authorization.
+- **[Authorize](operations/Authorize.md)** - Reserve payer funds in escrow for future capture. Enables delayed settlement while guaranteeing merchant payment upon successful authorization.
 
 - **[Charge](operations/Charge.md)** - Combine authorization and capture into a single transaction for immediate payment settlement.
 
 ### Payment Settlement  
 - **[Capture](operations/Capture.md)** - Transfer previously authorized funds from escrow to merchants. Supports partial captures and flexible fee distribution.
 
 ### Payment Cancellation
-- **[Void](operations/Void.md)** - Cancel payment authorizations and return escrowed funds to buyers. Only callable by the operator, but can be used to cancel a payment at any time.
+- **[Void](operations/Void.md)** - Cancel payment authorizations and return escrowed funds to payerss. Only callable by the operator, but can be used to cancel a payment at any time.
 
-- **[Reclaim](operations/Reclaim.md)** - Allow buyers to recover funds from expired authorizations. Buyer-initiated safety mechanism callable only after authorization expiry.
+- **[Reclaim](operations/Reclaim.md)** - Allow payers to recover funds from expired authorizations. Payer-initiated safety mechanism callable only after authorization expiry.
 
 ### Payment Reversal
-- **[Refund](operations/Refund.md)** - Return previously captured funds to buyers using modular refund collectors. Supports partial refunds and flexible liquidity sourcing.
+- **[Refund](operations/Refund.md)** - Return previously captured funds to payers using modular refund collectors. Supports partial refunds and flexible liquidity sourcing.
 
 
 ## Contract Architecture
@@ -48,14 +49,14 @@ The protocol provides six main functions that handle the complete payment lifecy
   <p><em>Commerce Payments Protocol smart contract architecture</em></p>
 </div>
 
-### 1. `AuthCaptureEscrow`
+### 1. [`AuthCaptureEscrow`](../src/AuthCaptureEscrow.sol)
 The main escrow contract that manages funds and payment lifecycle:
 - Validates payment parameters and timing constraints
 - Manages payment state (authorized, captured, refunded)
 - Handles fee distribution
 - Ensures atomic operations with reentrancy protection
 
-### 2. Token Collectors
+### 2. [Token Collectors](TokenCollectors.md)
 Pluggable payment modules that handle different authorization methods.
 See [Token Collectors](TokenCollectors.md) for complete documentation.
 - **ERC3009PaymentCollector**: Uses ERC-3009 `receiveWithAuthorization` signatures
@@ -64,7 +65,7 @@ See [Token Collectors](TokenCollectors.md) for complete documentation.
 - **SpendPermissionPaymentCollector**: Uses Coinbase's Spend Permission system
 - **OperatorRefundCollector**: Handles refunds from operator funds
 
-### 3. Token Stores
+### 3. [Token Stores](../src/TokenStore.sol)
 Per-operator token vaults that hold escrowed funds.
 See [Liquidity Segmentation](Security.md#liquidity-segmentation-in-operator-tokenstores) for complete documentation.
 
@@ -74,18 +75,18 @@ See [Liquidity Segmentation](Security.md#liquidity-segmentation-in-operator-toke
 
 
 
-## Payment Info Structure
+## [PaymentInfo](../src/AuthCaptureEscrow.sol#L26-L52) Structure
 
 Every payment is defined by a `PaymentInfo` struct containing immutable terms. A payment is uniquely identified by the hash of this struct, further hashed with the chain id and hashing contract address.
 
 ```solidity
 struct PaymentInfo {
     address operator;           // Entity managing the payment flow
-    address payer;              // Buyer's wallet address
+    address payer;              // Payer's wallet address
     address receiver;           // Merchant's receiving address
     address token;              // Payment token contract
     uint120 maxAmount;          // Maximum amount that can be authorized
-    uint48 preApprovalExpiry;   // When buyer's willingness to authorize the payment expires
+    uint48 preApprovalExpiry;   // When payer's willingness to authorize the payment expires
     uint48 authorizationExpiry; // When an authorized payment can no longer be captured and can now be reclaimed
     uint48 refundExpiry;        // When refunds are no longer allowed
     uint16 minFeeBps;           // Minimum fee in basis points
@@ -105,4 +106,4 @@ The protocol implements a flexible fee mechanism with configurable rates and rec
 
 The protocol incorporates multiple security layers including access controls, time-based constraints, balance verification, and liquidity segmentation. The trust-minimized operator model ensures that while operators control payment flows, they cannot steal funds and have limited ability to cause harm.
 
-**🔒 [Security Analysis](Security.md)** - Comprehensive security features, risk assessment, and mitigation strategies including operator compromise scenarios and token denylist considerations.
+**🔒 [Security Analysis](Security.md)** - Comprehensive protocol guarantees, security features, risk and mitigation strategies including operator compromise scenarios and token denylist considerations.