refactor(examples,sdk): simplify lifecycle example to single-wallet flow and enhance error handling with custom error decoding

- Refactor lifecycle.rs to use one private key for all roles (client/provider/evaluator) with inline documentation explaining contract validates msg.sender, not role distinctness
- Add IERC20 approve step before funding to show complete USDC interaction pattern
- Replace separate connect() helper with inline provider setup using network.rpc_url()
- Add contract_address() getter

Author: gitctrlx

erc8183/examples/lifecycle.rs

@@ -1,97 +1,90 @@
 //! Complete lifecycle on Monad Mainnet: `Open → Funded → Submitted → Completed`.
 //!
+//! A single private key plays all three roles (client, provider, evaluator).
+//! This is valid because the contract checks `msg.sender == role_address`,
+//! not that the roles are distinct addresses.
+//!
 //! ```sh
-//! export RPC_URL=https://rpc.monad.xyz
-//! export CLIENT_KEY=0xac0974...
-//! export PROVIDER_KEY=0x59c699...
-//! export EVALUATOR_KEY=0x5de411...
+//! export PRIVATE_KEY=0xac0974...
 //! cargo run --example lifecycle
 //! ```
 
-use std::env;
+use std::{env, time::SystemTime};
 
 use alloy::{
     network::EthereumWallet,
-    primitives::{Address, FixedBytes, U256},
-    providers::{Provider, ProviderBuilder},
-    signers::local::PrivateKeySigner,
+    primitives::{FixedBytes, U256},
+    providers::ProviderBuilder,
+    sol,
 };
-use erc8183::{Erc8183, Network, job::JobHandle, types::CreateJobParams};
-
-fn connect(
-    rpc: &str,
-    key_env: &str,
-) -> Result<(Erc8183<impl Provider>, Address), Box<dyn std::error::Error>> {
-    let signer: PrivateKeySigner = env::var(key_env)?.parse()?;
-    let addr = signer.address();
-    let sdk = Erc8183::new(
-        ProviderBuilder::new()
-            .wallet(EthereumWallet::from(signer))
-            .connect_http(rpc.parse()?),
-    )
-    .with_network(Network::MonadMainnet);
-    Ok((sdk, addr))
-}
-
-/// Client: create job → set budget → fund escrow.
-async fn client_create_and_fund<P: Provider>(
-    job: &JobHandle<P>,
-    provider: Address,
-    evaluator: Address,
-) -> erc8183::Result<U256> {
-    let params = CreateJobParams::new(
-        provider,
-        evaluator,
-        U256::from(u64::MAX),
-        "Analyze market data",
-    );
-    let id = job.create_job(&params).await?;
-    let budget = U256::from(1_000_000u64);
-    job.set_budget(id, budget, None).await?;
-    job.fund(id, budget, None).await?;
-    Ok(id)
-}
+use erc8183::{Erc8183, Network, types::CreateJobParams};
 
-/// Provider: submit work deliverable.
-async fn provider_submit<P: Provider>(job: &JobHandle<P>, id: U256) -> erc8183::Result<()> {
-    job.submit(id, FixedBytes::from([0xAB; 32]), None).await
+sol! {
+    #[sol(rpc)]
+    interface IERC20 {
+        function approve(address spender, uint256 amount) external returns (bool);
+    }
 }
 
-/// Evaluator: attest completion → release escrow.
-async fn evaluator_complete<P: Provider>(job: &JobHandle<P>, id: U256) -> erc8183::Result<()> {
-    job.complete(id, FixedBytes::ZERO, None).await
+fn now_secs() -> u64 {
+    SystemTime::now()
+        .duration_since(SystemTime::UNIX_EPOCH)
+        .expect("system clock before epoch")
+        .as_secs()
 }
 
 #[allow(clippy::print_stdout)]
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
-    let rpc = env::var("RPC_URL")?;
+    let network = Network::MonadMainnet;
+    let signer: alloy::signers::local::PrivateKeySigner = env::var("PRIVATE_KEY")?.parse()?;
+    let addr = signer.address();
+
+    let provider = ProviderBuilder::new()
+        .wallet(EthereumWallet::from(signer))
+        .connect_http(network.rpc_url().parse()?);
 
-    let (client_sdk, _) = connect(&rpc, "CLIENT_KEY")?;
-    let (provider_sdk, provider_addr) = connect(&rpc, "PROVIDER_KEY")?;
-    let (evaluator_sdk, evaluator_addr) = connect(&rpc, "EVALUATOR_KEY")?;
+    let sdk = Erc8183::new(&provider).with_network(network);
+    let job = sdk.job()?;
 
-    let client = client_sdk.job()?;
-    let provider = provider_sdk.job()?;
-    let evaluator = evaluator_sdk.job()?;
+    println!("Network:  {network}");
+    println!("Contract: {}", job.contract_address());
+    println!("Wallet:   {addr}\n");
+
+    // 1. Create job — one wallet is client, provider, and evaluator
+    let expires_at = U256::from(now_secs() + 3600);
+    let params = CreateJobParams::new(addr, addr, expires_at, "Analyze market data");
+    let id = job.create_job(&params).await?;
+    println!("[1/5] Created job #{id}");
 
-    // Open → Funded → Submitted → Completed
-    let id = client_create_and_fund(&client, provider_addr, evaluator_addr).await?;
-    println!("[Client]    Created & funded job #{id}");
+    // 2. Set budget (1 USDC = 1_000_000 units with 6 decimals)
+    let budget = U256::from(1_000_000u64);
+    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?;
+    println!("[3/5] Funded escrow");
 
-    provider_submit(&provider, id).await?;
-    println!("[Provider]  Submitted deliverable");
+    // 4. Submit work deliverable
+    job.submit(id, FixedBytes::from([0xAB; 32]), None).await?;
+    println!("[4/5] Submitted deliverable");
 
-    evaluator_complete(&evaluator, id).await?;
-    println!("[Evaluator] Completed — payment released");
+    // 5. Evaluator completes — releases payment
+    job.complete(id, FixedBytes::ZERO, None).await?;
+    println!("[5/5] Completed — payment released");
 
-    let job = client.get_job(id).await?;
-    println!(
-        "\nJob #{}: {} (terminal: {})",
-        job.id,
-        job.status,
-        job.status.is_terminal()
-    );
+    // Query final state
+    let data = job.get_job(id).await?;
+    println!("\n{data}");
+    println!("Terminal: {}", data.status.is_terminal());
 
     Ok(())
 }

erc8183/src/client.rs

@@ -8,14 +8,14 @@
 //! use erc8183::{Erc8183, Network};
 //!
 //! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
+//! let network = Network::MonadMainnet;
 //! let provider = ProviderBuilder::new()
-//!     .connect_http("https://monad-rpc.example.com".parse()?);
+//!     .connect_http(network.rpc_url().parse()?);
 //!
-//! // Built-in network (Monad Mainnet)
-//! let client = Erc8183::new(provider)
-//!     .with_network(Network::MonadMainnet);
-//!
-//! let job = client.job()?.get_job(U256::from(1)).await?;
+//! let job = Erc8183::new(provider)
+//!     .with_network(network)
+//!     .job()?
+//!     .get_job(U256::from(1)).await?;
 //! # Ok(())
 //! # }
 //! ```
@@ -44,11 +44,12 @@ use crate::{
 /// use erc8183::{Erc8183, Network};
 ///
 /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
+/// let network = Network::MonadMainnet;
 /// let client = Erc8183::new(
 ///     ProviderBuilder::new()
-///         .connect_http("https://monad-rpc.example.com".parse()?),
+///         .connect_http(network.rpc_url().parse()?),
 /// )
-/// .with_network(Network::MonadMainnet);
+/// .with_network(network);
 /// # Ok(())
 /// # }
 /// ```

erc8183/src/error.rs

@@ -1,6 +1,8 @@
 //! Typed error definitions for the ERC-8183 SDK.
 
-use alloy::primitives::U256;
+use alloy::sol_types::SolError;
+
+use crate::contracts::AgenticCommerce;
 
 /// The primary error type for all ERC-8183 SDK operations.
 #[derive(Debug, thiserror::Error)]
@@ -17,11 +19,11 @@ pub enum Error {
     #[error("contract not configured")]
     ContractNotConfigured,
 
-    /// The requested job does not exist on-chain.
-    #[error("job {job_id} does not exist")]
-    JobNotFound {
-        /// The queried job ID.
-        job_id: U256,
+    /// Expected event was not found in a transaction receipt.
+    #[error("event not found in receipt: {context}")]
+    EventNotFound {
+        /// Description of which event was expected.
+        context: &'static str,
     },
 
     /// A pending transaction was dropped or failed to confirm.
@@ -42,3 +44,41 @@ pub enum Error {
 
 /// A convenience type alias used throughout the SDK.
 pub type Result<T> = core::result::Result<T, Error>;
+
+/// Decode a 4-byte revert selector into a human-readable error name.
+///
+/// Returns the error name if it matches a known `AgenticCommerce` custom
+/// error, or `None` for unrecognized selectors.
+///
+/// # Examples
+///
+/// ```
+/// assert_eq!(
+///     erc8183::error::decode_revert_reason(&[0xd3, 0x6c, 0x85, 0x00]),
+///     Some("InvalidExpiry"),
+/// );
+/// ```
+#[must_use]
+pub fn decode_revert_reason(data: &[u8]) -> Option<&'static str> {
+    let sel: [u8; 4] = data.get(..4)?.try_into().ok()?;
+    match sel {
+        AgenticCommerce::ZeroAddress::SELECTOR => Some("ZeroAddress"),
+        AgenticCommerce::InvalidExpiry::SELECTOR => Some("InvalidExpiry"),
+        AgenticCommerce::InvalidStatus::SELECTOR => Some("InvalidStatus"),
+        AgenticCommerce::Unauthorized::SELECTOR => Some("Unauthorized"),
+        AgenticCommerce::ProviderAlreadySet::SELECTOR => Some("ProviderAlreadySet"),
+        AgenticCommerce::ProviderNotSet::SELECTOR => Some("ProviderNotSet"),
+        AgenticCommerce::BudgetMismatch::SELECTOR => Some("BudgetMismatch"),
+        AgenticCommerce::ZeroBudget::SELECTOR => Some("ZeroBudget"),
+        AgenticCommerce::JobAlreadyExpired::SELECTOR => Some("JobAlreadyExpired"),
+        AgenticCommerce::JobNotExpired::SELECTOR => Some("JobNotExpired"),
+        AgenticCommerce::FeeTooHigh::SELECTOR => Some("FeeTooHigh"),
+        AgenticCommerce::JobDoesNotExist::SELECTOR => Some("JobDoesNotExist"),
+        AgenticCommerce::HookNotWhitelisted::SELECTOR => Some("HookNotWhitelisted"),
+        AgenticCommerce::HookInterfaceNotSupported::SELECTOR => Some("HookInterfaceNotSupported"),
+        AgenticCommerce::DescriptionTooLong::SELECTOR => Some("DescriptionTooLong"),
+        AgenticCommerce::OwnableUnauthorizedAccount::SELECTOR => Some("OwnableUnauthorizedAccount"),
+        AgenticCommerce::OwnableInvalidOwner::SELECTOR => Some("OwnableInvalidOwner"),
+        _ => None,
+    }
+}

erc8183/src/job.rs

@@ -48,6 +48,12 @@ impl<P: Provider> JobHandle<P> {
         Self { address, provider }
     }
 
+    /// Returns the contract address this handle points to.
+    #[must_use]
+    pub const fn contract_address(&self) -> Address {
+        self.address
+    }
+
     /// Standard ERC-8183 interface — portable across any compliant contract.
     const fn standard(&self) -> IERC8183::IERC8183Instance<&P> {
         IERC8183::new(self.address, &self.provider)
@@ -476,8 +482,8 @@ impl<P: Provider> JobHandle<P> {
                     .ok()
                     .map(|e| e.inner.data.jobId)
             })
-            .ok_or(Error::Contract(alloy::contract::Error::UnknownFunction(
-                "createJob: no JobCreated event found".to_owned(),
-            )))
+            .ok_or(Error::EventNotFound {
+                context: "JobCreated event not found in createJob receipt",
+            })
     }
 }

erc8183/src/lib.rs

@@ -17,30 +17,28 @@
 //! use erc8183::{Erc8183, Network, types::CreateJobParams};
 //!
 //! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
-//! // 1. Create an alloy provider (any transport works: HTTP, WS, IPC)
+//! // 1. Connect using the built-in RPC URL
+//! let network = Network::MonadMainnet;
 //! let provider = ProviderBuilder::new()
-//!     .connect_http("https://monad-rpc.example.com".parse()?);
+//!     .connect_http(network.rpc_url().parse()?);
 //!
-//! // 2. Wrap it with the ERC-8183 client
-//! let client = Erc8183::new(provider)
-//!     .with_network(Network::MonadMainnet);
+//! // 2. Create client and get a job handle
+//! let job = Erc8183::new(provider)
+//!     .with_network(network)
+//!     .job()?;
 //!
-//! // 3. Get a job handle for contract interactions
-//! let job = client.job()?;
-//!
-//! // 4. Create a job (requires signer-enabled provider)
+//! // 3. Create a job (requires signer-enabled provider)
 //! let params = CreateJobParams::new(
 //!     Address::ZERO,                // deferred provider
 //!     "0xEvaluator...".parse()?,    // evaluator
 //!     U256::from(1_700_000_000u64), // expiredAt
 //!     "Build a REST API",           // description
 //! );
 //! let job_id = job.create_job(&params).await?;
-//! println!("Created job: {job_id}");
 //!
-//! // 5. Query job data
+//! // 4. Query job data
 //! let data = job.get_job(job_id).await?;
-//! println!("Job status: {}", data.status);
+//! println!("{data}"); // "Job #1 [Open] budget=0 client=0x... provider=0x..."
 //! # Ok(())
 //! # }
 //! ```

erc8183/src/networks.rs

@@ -9,6 +9,9 @@
 
 use alloy::primitives::{Address, address};
 
+const MONAD_MAINNET_RPC: &str = "https://rpc.monad.xyz";
+const MONAD_MAINNET_EXPLORER: &str = "https://monad.socialscan.io";
+
 /// The Monad Mainnet `AgenticCommerce` deployment.
 const MONAD_MAINNET: Address = address!("E8c4FFb4A6F7B8040a7AE39F6651290E06A40725");
 
@@ -40,6 +43,28 @@ impl Network {
         }
     }
 
+    /// Returns the public RPC endpoint URL for this network.
+    #[must_use]
+    pub const fn rpc_url(self) -> &'static str {
+        match self {
+            Self::MonadMainnet => MONAD_MAINNET_RPC,
+        }
+    }
+
+    /// Returns the block explorer base URL for this network.
+    #[must_use]
+    pub const fn explorer_base_url(self) -> &'static str {
+        match self {
+            Self::MonadMainnet => MONAD_MAINNET_EXPLORER,
+        }
+    }
+
+    /// Returns a block explorer URL for a given contract address.
+    #[must_use]
+    pub fn explorer_url(self, address: Address) -> String {
+        format!("{}/address/{address}", self.explorer_base_url())
+    }
+
     /// All known ERC-8183 network variants.
     pub const ALL: &[Self] = &[Self::MonadMainnet];
 
@@ -51,3 +76,11 @@ impl Network {
         Self::ALL.iter().find(|n| n.chain_id() == chain_id).copied()
     }
 }
+
+impl std::fmt::Display for Network {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::MonadMainnet => write!(f, "Monad Mainnet"),
+        }
+    }
+}