feat(sdk): add approve_and_fund convenience method and payment token helpers

- Add IERC20 interface to contracts.rs with approve/allowance/balanceOf functions
- Implement approve_payment_token() for explicit token approval before funding
- Add approve_and_fund() convenience method combining approval + funding in single call
- Add payment_token_allowance() and payment_token_balance() query helpers
- Simplify lifecycle.rs example by replacing manual IERC20 approval with approve_and_fund()
- Remove

Author: gitctrlx

erc8183/examples/lifecycle.rs

@@ -15,17 +15,9 @@ use alloy::{
     network::EthereumWallet,
     primitives::{FixedBytes, U256},
     providers::ProviderBuilder,
-    sol,
 };
 use erc8183::{Erc8183, Network, types::CreateJobParams};
 
-sol! {
-    #[sol(rpc)]
-    interface IERC20 {
-        function approve(address spender, uint256 amount) external returns (bool);
-    }
-}
-
 fn now_secs() -> u64 {
     SystemTime::now()
         .duration_since(SystemTime::UNIX_EPOCH)
@@ -62,15 +54,8 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     job.set_budget(id, budget, None).await?;
     println!("[2/5] Budget set: {budget} (1 USDC)");
 
-    // 3. Approve USDC spend, then fund escrow
-    let usdc = job.payment_token().await?;
-    IERC20::new(usdc, &provider)
-        .approve(job.contract_address(), budget)
-        .send()
-        .await?
-        .get_receipt()
-        .await?;
-    job.fund(id, budget, None).await?;
+    // 3. Approve USDC + fund escrow (single convenience call)
+    job.approve_and_fund(id, budget, None).await?;
     println!("[3/5] Funded escrow");
 
     // 4. Submit work deliverable

erc8183/src/contracts.rs

@@ -18,6 +18,20 @@
 
 use alloy::sol;
 
+sol! {
+    /// Minimal ERC-20 interface for token approval operations.
+    ///
+    /// Only includes `approve` and `allowance` — the two functions needed
+    /// to interact with the payment token before funding a job.
+    #[allow(missing_docs)]
+    #[sol(rpc)]
+    interface IERC20 {
+        function approve(address spender, uint256 amount) external returns (bool);
+        function allowance(address owner, address spender) external view returns (uint256);
+        function balanceOf(address account) external view returns (uint256);
+    }
+}
+
 sol! {
     /// IERC8183 — Standard interface for the Agentic Commerce Protocol.
     ///

erc8183/src/job.rs

@@ -21,7 +21,7 @@ use alloy::{
 };
 
 use crate::{
-    contracts::{AgenticCommerce, IERC8183},
+    contracts::{AgenticCommerce, IERC20, IERC8183},
     error::{Error, Result},
     types::{CreateJobParams, Job, JobStatus},
 };
@@ -254,6 +254,71 @@ impl<P: Provider> JobHandle<P> {
         Ok(())
     }
 
+    /// Approve the payment token for the contract to spend.
+    ///
+    /// This is a prerequisite for [`fund`](Self::fund). The contract must be
+    /// approved to transfer at least `amount` tokens from the caller.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the transaction fails.
+    pub async fn approve_payment_token(&self, amount: U256) -> Result<()> {
+        let token = self.contract().PAYMENT_TOKEN().call().await?;
+        IERC20::new(token, &self.provider)
+            .approve(self.address, amount)
+            .send()
+            .await?
+            .get_receipt()
+            .await?;
+        Ok(())
+    }
+
+    /// Approve and fund in one call: approve the payment token, then fund
+    /// the escrow.
+    ///
+    /// Convenience method that combines
+    /// [`approve_payment_token`](Self::approve_payment_token) +
+    /// [`fund`](Self::fund).
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if either transaction fails.
+    pub async fn approve_and_fund(
+        &self,
+        job_id: U256,
+        expected_budget: U256,
+        opt_params: Option<Bytes>,
+    ) -> Result<()> {
+        self.approve_payment_token(expected_budget).await?;
+        self.fund(job_id, expected_budget, opt_params).await
+    }
+
+    /// Get the caller's current allowance for the payment token.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the RPC call fails.
+    pub async fn payment_token_allowance(&self, owner: Address) -> Result<U256> {
+        let token = self.contract().PAYMENT_TOKEN().call().await?;
+        Ok(IERC20::new(token, &self.provider)
+            .allowance(owner, self.address)
+            .call()
+            .await?)
+    }
+
+    /// Get the caller's payment token balance.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the RPC call fails.
+    pub async fn payment_token_balance(&self, account: Address) -> Result<U256> {
+        let token = self.contract().PAYMENT_TOKEN().call().await?;
+        Ok(IERC20::new(token, &self.provider)
+            .balanceOf(account)
+            .call()
+            .await?)
+    }
+
     /// Claim a refund after job expiry.
     ///
     /// Anyone may call this when `block.timestamp >= job.expiredAt` and the