> ## 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.

# How Tavryn Works: 7-Stage Autonomous Procurement Loop

> A stage-by-stage breakdown of Tavryn's 7-step autonomous loop — from the 45-day renewal scan through on-chain USDC escrow release and continuous learning.

Tavryn does not simply surface a savings suggestion and wait for a human to act on it. It executes an end-to-end autonomous procurement loop: detecting waste, evaluating alternatives, negotiating with vendors, auditing the result, enforcing policy, settling payment on-chain, and feeding the outcome back into future negotiations. Every stage has deterministic guardrails so the system remains auditable, predictable, and fully under your control at every financial decision boundary.

## The 7-stage autonomous loop

**1. Observe — scan renewals and audit waste**

Tavryn begins evaluating each contract **45 days before its renewal date**, triggered either by the daily proactive cron job (`GET /api/cron/daily` at 08:00 UTC) or manually via `POST /api/agent/run-now`.

During this stage, the agent runs two deterministic waste audits:

* **Seat waste** — compares provisioned seats against active seats. If 40 seats are provisioned but only 28 are active, the agent calculates the exact USDC savings from right-sizing the renewal.
* **Usage decline** — measures the percentage drop in cloud or API consumption. A significant decline signals overpayment relative to actual utilization.

Both calculations use deterministic heuristics — not LLM inference — so the waste figures are fully reproducible and verifiable.

**2. Compare — compute the switch vs. renegotiate NPV matrix**

Before negotiating, Tavryn evaluates whether staying with the current vendor is the right decision at all. The switch vs. renegotiate matrix computes 1-year and 2-year net present value for two scenarios:

* **Renegotiate** — projected savings from a discounted renewal with the incumbent vendor.
* **Switch** — net benefit of migrating to a top competitor alternative, minus migration engineering hours, employee retraining cost, and estimated downtime risk.

> [!WARNING]
>
> Switching to a new vendor **always requires human approval**, regardless of NPV. The invariant `requiresHumanApproval = true` is enforced unconditionally before any vendor migration can proceed. The agent cannot autonomously migrate your organization to a new vendor.

If renegotiation has a higher NPV, the agent proceeds to Stage 3. If switching has a higher NPV, Tavryn flags the contract for supervisor review and pauses autonomous execution.

**3. Negotiate — run multi-round concession curves**

Tavryn executes structured multi-round negotiations (up to 5 rounds by default) against the vendor. Each round is calibrated by:

* **Historical deal memory** — past negotiation outcomes with this vendor, including floors reached and concession speeds observed.
* **Competitor quotes** — alternative pricing pulled from the switch matrix to anchor the negotiation.
* **Walk-away ceiling** — a hard maximum price above which the agent will not agree to renew, derived from your policy configuration and the calculated waste figures.

The agent cites specific data points in each round — idle seat counts, usage decline percentages, competitor prices — to apply structured pressure rather than generic discount requests.

In demo mode, simulated vendors use reproducible concession curves so every demo run is predictable and consistent. In production, real vendors are handled through human-in-the-loop AI outreach drafting with structured reply parsing.

**4. Review — adversarial reviewer issues a verdict**

Before any deal reaches the policy engine, an independent **Adversarial Reviewer Agent** audits the proposed outcome. The reviewer performs two passes:

* **Deterministic benchmark checks** — verifies the proposed discount against known market benchmarks and seat utilization data.
* **Qualitative LLM audit** — inspects concession speed (did the vendor cave too quickly, suggesting the floor was set too high?) and flags suspicious terms.

The reviewer issues one of three verdicts:

| Verdict | Meaning |
| - | - |
| `AGREE` | Deal terms are reasonable; proceed to policy evaluation |
| `CHALLENGE` | One or more terms warrant re-negotiation; agent may loop back to Stage 3 |
| `REJECT` | Deal is outside acceptable parameters; escalate to supervisor for manual review |

A `CHALLENGE` or `REJECT` verdict suspends autonomous execution and notifies your configured webhook (Discord or Slack).

**5. Decide — deterministic policy engine evaluates the deal**

The policy engine is the financial decision boundary of the entire system. It evaluates every `AGREE`-rated deal against your organization's spending configuration using **pure deterministic logic** — no LLM inference, no probabilistic scoring.

> [!NOTE]
>
> The LLM **cannot approve transactions**. Only the deterministic policy engine can authorize execution. This is an architectural invariant, not a configurable setting.

The engine checks four conditions:

| Check | Policy Field | Outcome if Failed |
| - | - | - |
| Deal value below auto-approval limit | `max_auto_transaction` | Generate HMAC approval link |
| Savings meet minimum threshold | `min_savings` | Block the deal |
| Category is permitted | `allowed_categories` | Block the deal |
| Value below human-required threshold | `human_approval_required_above` | Generate HMAC approval link |

Deals that require human approval trigger a single-use HMAC-SHA256 link valid for 48 hours. The link routes to `/approve/[token]`, where you can preview the full deal summary and approve or reject with one authenticated POST. Policy is re-verified server-side at redemption time — a stale approval cannot execute a deal that has since fallen outside policy.

**6. Execute — escrow USDC on Arc via Circle wallets**

Once the policy engine (or a human supervisor) authorizes execution, Tavryn uses Circle Developer-Controlled Wallets to sign and submit an on-chain transaction to the `ArcEscrow` smart contract on Arc Testnet:

* **Contract address**: `0x78e61ae7e8EeF34Add911FA3e41F3408a819c047`
* **USDC precompile**: `0x3600000000000000000000000000000000000000` (6 decimals)
* **Chain ID**: `5042002` (Arc Layer-1 Testnet)

The escrow contract:

1. Locks commitment funds plus the protocol success fee (capped at 20% / 2,000 bps) on `createAgreement` + `fundAgreement`.
2. Enforces a per-agreement maximum of 10,000 USDC in EVM bytecode.
3. Separates roles: the Agent role creates and funds agreements; only the Verifier role can call `releasePayment`.

The Fulfillment Verification Engine then extracts terms from the vendor's counter-signed order receipt and performs a **4-field document match**: price, seats, term length, and effective date must all match the negotiated terms exactly. Funds are released only on a clean match. Concurrency is guarded by server-side idempotency locking and on-chain idempotency keys to prevent double-payments.

Private keys are never held in application memory or accessible to any LLM component. All signing happens server-side via the Circle Entity Secret ciphertext flow.

**7. Learn — capture overrides and update vendor reputation**

After each completed cycle — whether the deal was approved, rejected, or overridden — Tavryn updates its persistent memory:

* **Override memory** — structured rejection reason codes from supervisor overrides are stored persistently and injected into future negotiation prompts for the same vendor.
* **Vendor reputation scores** — each vendor maintains a reputation score in the range \[10, 100]. Scores update based on negotiation outcomes: +12 for a smooth auto-approved deal, +8 for a supervisor-approved deal, +5 for a challenged deal that resolved cleanly.
* **Concession speed benchmarks** — the agent records how quickly each vendor moved to its floor, refining the opening anchor and walk-away ceiling in future rounds.

This feedback loop means Tavryn's negotiations improve with every cycle, building an organization-specific procurement intelligence layer that no static playbook can replicate.

## Security and auditability

Every agent action — waste calculation, negotiation round, reviewer verdict, policy decision, escrow event — is written to an append-only audit ledger with a SHA-256 hash linking each record to the previous one. Database triggers block any `UPDATE` or `DELETE` attempt, making the ledger tamper-proof at the database level.

> [!TIP]
>
> Visit `/audit` to view the cryptographic audit ledger and verify the SHA-256 hash chain integrity in real time. Every entry is tamper-evident: a single modified record breaks the chain and is immediately visible.

Tenant isolation is enforced by Row-Level Security across all database tables — authenticated users of one business cannot read or modify contracts, negotiations, policies, or audit records belonging to another business.


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