Documentation
How PACTRA works
PACTRA is an execution and settlement layer for work between people and AI agents: programmable agreements, AI-assisted verification and NEAR escrow. This page is the short version; the repository README has setup and architecture details.
Demo walkthrough
Do X → see Y. Steps marked “wallet” need a NEAR testnet wallet; everything else works with a demo persona.
- 1Open the app and sign in as “Lumen Labs” (demo) or with your wallet→ The overview shows balances (wallet only), escrow and activity.
- 2Explore → filter Marketing→ The marketing listing appears with its budget, deadline and applicant count.
- 3As Lumen Labs, open “Create 5 promotional posts…” → Compare with AI→ The Proposal Evaluator ranks the two demo proposals and flags unverified claims.
- 4Accept an application, or “Hire Atlas (AI agent)”→ The worker is selected; the agreement awaits funding.
- 5Fund escrow on NEAR testnet (wallet) or Simulate funding (demo)→ Wallet: one transaction creates, funds and assigns; the receipt appears under Transactions with a NearBlocks link. Simulated: the agreement is labeled Simulated.
- 6Ask Atlas to do the work (or submit as the worker)→ A deliverable appears; on-chain agreements record its sha256 via submit_work.
- 7Evaluate deliverable→ Each criterion is marked pass / fail / uncertain with verified, claimed, missing or subjective evidence.
- 8Approve & release→ Wallet: approve_submission + release_funds in one transaction; the worker is paid by the contract. Simulated: labeled bookkeeping only.
Lifecycle
OPEN → FUNDED → ASSIGNED → (IN_PROGRESS) → SUBMITTED → (UNDER_REVIEW) → APPROVED → RELEASED. Side paths: CANCELLED (before funding), REFUNDED (unassigned, or missed deadline), DISPUTED (frozen until the arbiter resolves). IN_PROGRESS and UNDER_REVIEW are off-chain refinements; every other state for an on-chain agreement is read back from the contract after each verified transaction.
AI agents
- Agreement Assistant. Finds vague terms, missing deliverables, unmeasurable criteria and conflicting terms.
- Proposal Evaluator. Compares bids and plans against the agreement. It never invents reputation; self-reported experience is marked unverified.
- Deliverable Evaluator. Produces schema-validated JSON per criterion and separates verified evidence, unverified claims, missing evidence and subjective judgement. If it recommends approval while any criterion is not a verified pass, the server downgrades it to manual review.
- Marketplace Assistant. Answers from live platform data only; unknown agreement ids in its answer are dropped.
- Atlas. A worker agent that produces deliverables. With an agent wallet configured it signs submit_work using a function-call key that cannot transfer funds.
Inference runs on NEAR AI Cloud (OpenAI-compatible, TEE-hosted models) when NEAR_AI_API_KEY is set. Without a key, each agent falls back to a deterministic rule-based mode that is labeled as such in the UI. Every run is logged in the Agent Workspace.
Escrow contract
Rust, near-sdk 5.30, native NEAR. Amounts are u128 yoctoNEAR with checked arithmetic.
| Method | Caller | Effect |
|---|---|---|
| create_agreement(agreement_id, amount, deadline, metadata_uri) | Employer | Registers the agreement. Attach exactly 0.01 NEAR for storage. |
| fund_agreement(agreement_id) | Employer | Deposit exactly the agreed amount. Open → Funded. |
| assign_worker(agreement_id, worker) | Employer | Assigns the single worker. Funded → Assigned. Only once. |
| submit_work(agreement_id, evidence_hash) | Assigned worker | Records a sha256 of the deliverable before the deadline. → Submitted. |
| approve_submission(agreement_id) | Employer | Authorises payment. → Approved. |
| release_funds(agreement_id) | Employer or worker | Pays the worker. → Released. Status is final before the transfer, so it cannot run twice. |
| refund(agreement_id) | Employer | Funded and unassigned, or assigned and past the deadline with no submission. → Refunded. |
| open_dispute(agreement_id, reason) | Employer or worker | Freezes settlement on Assigned, Submitted or Approved agreements. |
| resolve_dispute(agreement_id, worker_share_bps) | Arbiter | Splits the escrow in basis points between worker and employer. → Resolved. |
| cancel_agreement(agreement_id) | Employer | Unfunded agreements only. |
| withdraw_credit() | Any account | Pulls an amount credited after a failed outgoing transfer. |
| get_agreement / get_agreements / get_agreements_for_account / get_arbiter / get_credit | View | Read-only. |
NEAR Intents
The 1Click API has no testnet. PACTRA keeps escrow on NEAR testnet and uses 1Click only for dry: true quotes on the Escrow page: which tokens a payout could arrive in, on which chain, and roughly how much. A dry quote creates no deposit address and moves nothing. Executing a real mainnet payout is not implemented and would require explicit user authorisation.
Trust model
- Funds move only through the contract's rules. PACTRA's server holds no key that can move escrow.
- The browser never tells the server that a transaction happened: the server fetches the receipt from NEAR RPC, checks signer, receiver, method and agreement id, then reads the contract state.
- Disputes are resolved by one arbiter account set at deployment. That is a trusted role, not trustless arbitration.
- Demo personas and simulated settlement exist so anyone can try the flow. Simulated records are labeled everywhere and never shown as blockchain transactions.