> ## Documentation Index
> Fetch the complete documentation index at: https://tavryn.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# USDC Escrow and On-Chain Settlement on Arc Network

> How Tavryn locks vendor payments in the ArcEscrow smart contract, enforces 4-field delivery verification, and releases funds trustlessly on Arc Testnet.

When Tavryn reaches an authorised deal with a vendor, the commitment doesn't live in a spreadsheet or a promise — it lives in a smart contract on a public blockchain. The `ArcEscrow` contract holds vendor payment and protocol fee in escrow until a verified order confirmation document proves the vendor delivered exactly what was agreed. No document match, no money. This page explains the contract architecture, the escrow lifecycle, and the network details you need to inspect any transaction independently.

## The ArcEscrow smart contract

`ArcEscrow` is a purpose-built Solidity contract deployed on the Arc Testnet. It encodes Tavryn's procurement policy directly into EVM bytecode — autonomously enforcing per-agreement spending limits and per-category budgets without relying on any off-chain service to police them.

**Deployed contract address:** [`0x78e61ae7e8EeF34Add911FA3e41F3408a819c047`](https://testnet.arcscan.app/address/0x78e61ae7e8EeF34Add911FA3e41F3408a819c047)

Key on-chain policy rules embedded in the contract:

* **Maximum per-agreement:** The Agent role cannot create an agreement whose total deposit (principal + protocol fee) exceeds **10,000 USDC**
* **Category budgets:** Cumulative spend per category is tracked on-chain and any agreement that would exceed its configured limit is rejected
* **Protocol success fee:** Capped at **20%** (2,000 basis points) of realised savings, configured by the contract owner and split to the protocol treasury on release
* **Reentrancy guard:** A mutex on fund and release operations prevents re-entrant calls from draining the contract

## Circle Developer-Controlled Wallets

Tavryn never holds private keys in application memory or exposes them to the LLM agent. Instead, all on-chain transactions are signed and submitted using **Circle Developer-Controlled Wallets** (`@circle-fin/developer-controlled-wallets`).

These are **server-side Smart Contract Account (SCA) wallets** where Circle's infrastructure manages key custody. Your Circle Entity Secret acts as an encryption ciphertext for transaction signing — it never leaves your server environment, and the LLM layer has no path to access it. Tavryn calls Circle's `createContractExecutionTransaction` API to submit each escrow operation, which Circle signs and broadcasts to the Arc network on your behalf.

> [!NOTE]
>
> **USDC is the native gas currency on Arc.** Unlike Ethereum, where ETH pays gas, Arc uses USDC (6 decimals) for both value transfer and transaction fees. This means your treasury balance covers both vendor payments and on-chain execution costs from a single asset — no separate gas token management required.

## Escrow lifecycle

Every vendor payment flows through five on-chain state transitions:

**1. createAgreement**

The Agent role calls `createAgreementWithSavings`, supplying the vendor address, negotiated amount, baseline price, category, and a deadline duration. The contract records the agreement, calculates the protocol success fee from realised savings (`savings × feeBps / 10000`), and emits `AgreementCreated`. The total deposit required is `amount + feeAmount`.

An **idempotency key** (a `bytes32` hash) is passed with every creation call. If the same key is presented twice — from a network retry or a race condition — the contract rejects the second call, preventing double-funding at the protocol level.

**2. fundAgreement**

The Agent calls `fundAgreement`, which pulls `amount + feeAmount` USDC from the depositor wallet via `transferFrom` and locks it in the contract. The agreement status advances to `Funded`. Funds are now held in the contract's USDC balance — neither Tavryn nor the vendor can access them unilaterally.

**3. submitMilestone**

Once the vendor's counter-signed order confirmation is received, the agent calls `submitMilestone` with a description of the delivery evidence. Status advances to `MilestoneSubmitted`.

**4. approveMilestone**

The **Verifier role** (a separate address from the Agent — the contract enforces `verifier != agent`) calls `approveMilestone` after the Fulfillment Verification Engine confirms a 4-field document match: **price, seats, term, and date** must all match the agreed terms exactly. Status advances to `MilestoneApproved`.

**5. releasePayment**

With the milestone approved, `release()` transfers `amount` USDC to the vendor and, if a protocol fee is configured, transfers `feeAmount` to the protocol treasury address. Both transfers must succeed or the entire call reverts — partial payment is impossible.

## Role separation

The contract enforces strict separation between the entity that creates agreements and the entity that releases funds:

| Role | Permissions |
| - | - |
| **Owner** | Configure fee rates, spending caps, category budgets, and role addresses |
| **Agent** | Create agreements, fund agreements, submit milestones |
| **Verifier** | Approve milestones only — cannot create or fund |

The contract constructor explicitly requires `verifier != agent`. This means even if the Agent role were compromised, an attacker could not approve their own milestones and release funds — the Verifier key is held separately.

## On cancellation

If a vendor fails to deliver within the agreement deadline, any party can call `refund()` once the on-chain deadline has passed. The contract returns 100% of the locked principal **and** the protocol fee to the depositor. The category budget tracking is also unwound — the refunded amount is subtracted from the category's cumulative spend.

> [!WARNING]
>
> Refunds are only available **after the deadline has passed**. Calling `refund()` before the deadline reverts on-chain. If you need to cancel an in-flight agreement before deadline expiry, contact your Tavryn administrator to arrange an off-chain resolution.

## Protocol success fee

The fee is calculated strictly on **realised savings** — the difference between the vendor's baseline contract price and the negotiated renewal price:

```text theme={null}
savings      = baselinePrice - negotiatedAmount
feeAmount    = (savings × feeBps) / 10000
totalDeposit = negotiatedAmount + feeAmount
```

The fee is capped at 2,000 basis points (20%). If no savings are realised, `feeAmount = 0` — Tavryn only earns when you save. The fee is locked alongside the principal at funding time and released to the protocol treasury atomically with the vendor payment.

## Network details

> [!NOTE]
>
> The following details refer to the Arc Testnet deployment. Mainnet addresses will be published when Arc Mainnet launches.

| Parameter | Value |
| - | - |
| **Chain ID** | `5042002` |
| **RPC endpoint** | `https://rpc.testnet.arc.network` |
| **Block explorer** | [https://testnet.arcscan.app](https://testnet.arcscan.app) |
| **ArcEscrow contract** | [`0x78e61ae7e8EeF34Add911FA3e41F3408a819c047`](https://testnet.arcscan.app/address/0x78e61ae7e8EeF34Add911FA3e41F3408a819c047) |
| **USDC precompile** | [`0x3600000000000000000000000000000000000000`](https://testnet.arcscan.app/address/0x3600000000000000000000000000000000000000) |
| **USDC decimals** | `6` |
| **Testnet faucet** | [https://faucet.circle.com](https://faucet.circle.com) |

You can verify any Tavryn escrow transaction independently by searching the agreement ID or transaction hash on ArcScan. The dashboard's Audit Ledger page links directly to ArcScan for every confirmed on-chain transaction.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.