PactAgent: From Application to Infrastructure

[Ajay]

Hi everyone,

I’d like to share a new developer update on PactAgent and get feedback from the Nervos CKB community.

For anyone seeing it for the first time, PactAgent is a milestone-based agreement and escrow workflow app built around Nervos CKB. The goal is to make direct work agreements, ecosystem bounties, and grant-style work easier to manage through clearer funding, proof submission, review, dispute, and settlement flows.

This update focuses on the recent UI redesign and improvements around DAO/bounty operations.

What I worked on recently

1. UI redesign across the app

I pushed a broad UI refresh across the main app experience, including the navbar, dashboard, agreement pages, and shared components.

The app now feels more like an operational workspace instead of a group of disconnected screens. The dashboard has been redesigned to make it easier to see:

• Which agreements need attention

• Who needs to act next

• What stage each agreement is in

• Where funding, review, or settlement risks may exist

The agreement page also now feels more like a live case file for each work agreement.

2. Agreement page improvements

The agreement detail page received a major upgrade.

It now gives clearer visibility into:

• Agreement status

• Next action

• Milestone progress

• Funding and settlement state

• Role-specific context

• Operational timeline

• Difference between direct agreements and imported work

For imported agreements, the funding section now shows more useful reserve information, such as reserve locked, reserve remaining, funding quote, and live quote comparison. This should make it easier for operators to understand whether the original funding still matches current quote conditions for unpaid work.

3. DAO/bounty import flow

I have also continued improving the forum-thread-to-agreement workflow.

Recent improvements include:

• Link-first import from a Nervos forum thread

• Source metadata capture and attribution

• Dynamic milestone extraction from source threads

• Imported grant context on the agreement page

• Stronger manual review framing

• Clearer imported workflow presentation across dashboard and detail pages

This is one area I am especially interested in getting feedback on. A lot of ecosystem work starts in a forum thread, but once execution begins, tracking progress, proof, funding, and settlement can become difficult. PactAgent is trying to help bridge that gap.

4. Imported grant funding and quote handling

I also improved the funding flow for imported grants, especially when the source budget is written in USD but the actual funding and settlement need to happen in CKB.

Recent improvements include:

• Live CKB/USD quote support

• Auto-filled CKB estimates from imported USD budgets

• Milestone-level USD-to-CKB helper inputs

• CKB-to-USD conversion helpers

• Total reserve visibility before funding

• Clearer post-funding quote awareness on the agreement page

The aim is to help operators fund reserves in CKB while still staying close to the original grant or bounty budget context.

5. Commencement payment support

For imported grants that include a separate kickoff or commencement payment, I improved the flow so that this payment does not have to be forced into Milestone 1.

This now supports:

• Commencement payment detection from source metadata

• Separate kickoff checkpoint behavior

• Clearer imported milestone structure

• Automatic kickoff release behavior after funding where applicable

This makes imported grant workflows more faithful to the original structure of the grant instead of flattening everything into a generic milestone model.

6. Proof review and human-in-the-loop controls

I also improved the proof and review layer so milestone approval can be more structured.

The current flow supports:

• Proof completeness checks

• Saved proof review states

• AI-drafted reviewer follow-up questions

• Structured reviewer information requests

• Worker responses to reviewer questions

• Human confirmation before high-stakes approval actions

The goal is not to let AI make payout decisions on its own. The goal is to reduce reviewer friction while keeping human approval in control of important decisions.

7. Source sync and governance-thread operations

Another important area is source sync for imported agreements.

Recent work includes:

• Agreement-page source sync controls

• Draft, review, and publish status flow

• Reviewer approval before outward posting

• Forum-aware sync behavior for Discourse-style threads

• Webhook support for source-sync events

This part is meant to connect agreement execution back to the original public governance thread, so updates do not get lost once work moves into execution.

8. Trust and ecosystem support features

Outside the core agreement flow, PactAgent now also has stronger support for:

• Public profiles

• Lightweight reputation views

• Invite links for draft agreements

• Webhook endpoint management

• Realtime agreement and activity updates

These features are meant to make PactAgent feel less like a one-time escrow tool and more like an operating layer for agreement coordination.

Why I’m sharing this

PactAgent is becoming more focused and opinionated.

The direction is now centered around:

• Direct milestone-based agreements

• DAO/bounty execution workflows

• Grant operations that connect source context, funding, proof, review, and settlement

This feels like the right direction to me, but I would really appreciate feedback from the community before pushing it further.

Feedback I’d appreciate

I’d especially like thoughts on these questions:

1. Does focusing PactAgent around direct agreements plus DAO/bounty imports make sense?

2. Would the dashboard and agreement-page direction be useful for real operators or reviewers?

3. Is the imported grant funding and live quote model understandable, or does it feel too complex?

4. Does separating commencement payments from normal milestones feel like the right approach?

5. Is the proof review plus human confirmation model credible for grant and bounty workflows?

6. Would source sync and forum update tooling be useful for Nervos ecosystem operations?

I have share screenshots of the current agreement lifecycle, import flow, and funding logic if that would make feedback easier.

Link to the repo and site:

https://github.com/Ajayfrizzy/pactagent

https://www.pactagent.online/

Thanks, and I’d really appreciate any thoughts or suggestions.

[Ajay]

Hi everyone,

I’d like to share a smaller follow-up update on PactAgent, focused mainly on the latest mobile view improvements.

After the previous UI redesign, I noticed that the desktop experience was becoming much stronger, but the mobile experience still needed more attention. Since PactAgent is meant to support operators, reviewers, clients, and workers who may need to check agreement status or take action quickly, I started improving the app so it feels more usable on smaller screens.

Latest mobile view improvements

I added a more mobile-friendly navigation structure across the app.

The mobile view now has a bottom navigation bar with the main actions:

• Home

• Dashboard

• Import

• Profile

• More

This makes the most important areas easier to reach without forcing users to rely on the desktop-style navigation.

I also moved secondary items like Webhooks into the More menu, while wallet access now sits separately in a hamburger menu. This helps keep the main mobile navigation cleaner and avoids overcrowding the bottom bar.

Mobile navigation state fixes

I also fixed some navigation state issues on mobile.

Previously, opening some menu sections could make the wrong page look active, especially around the Profile and More areas. That has now been improved so the active state better reflects what the user is actually viewing.

This should make the mobile experience feel less confusing when switching between agreement operations, profile settings, webhook settings, and other supporting pages.

Responsive layout improvements

I continued improving responsiveness across several screens, including:

• Dashboard

• Profile settings

• Webhook settings

• Agreement detail actions

• Admin replay actions

• Form flows

On smaller screens, key dashboard actions now stack better, buttons are easier to tap, and important action areas use the available width more effectively.

I also improved layouts where long content could break the mobile view. For example, webhook URLs, event labels, JSON examples, and long cards now wrap or scroll more cleanly instead of overflowing the screen.

Better mobile error and loading states

I also tightened some user feedback states.

Backend and wallet-related errors now show clearer messages instead of exposing large raw error responses in the UI. Loading states, pointer behavior, and button feedback are also more consistent across the agreement and admin flows.

Why this matters

The goal is to make PactAgent feel less like a desktop-only prototype and more like an agreement operations tool that can be checked and used from a phone.

This matters especially for workflows like:

• Reviewing agreement status

• Checking who needs to act next

• Viewing imported bounty or grant progress

• Managing proof review

• Checking funding or settlement state

• Responding to agreement actions while away from a laptop

There is still more mobile polish to do, but this update makes the app much more practical on smaller screens.

I’d appreciate feedback from anyone who tests the mobile view, especially around:

1. Whether the bottom navigation feels clear enough

2. Whether the More menu placement makes sense

3. Whether agreement and dashboard actions are easy to use on mobile

4. Any layout issues you notice on small screens

Thanks again to everyone following the progress of PactAgent.

[ArthurZhang]

hi ajay, great work, just one question I was curious about, how does PactAgent handle cases where there is a disagreement on milestone completion?

for example, a builder submits proof and considers the milestone completed, but the reviewer disagrees and rejects it. Is there an escalation/dispute resolution flow, or is the decision ultimately handled by a assigned reviewer/commitee?

[Ajay]

Hi Arthur, thanks for the question.

PactAgent separates proof review from dispute settlement. When a builder submits proof, the client/reviewer can approve it or request additional information. The builder’s submission alone does not mark the milestone as completed or release payment.

If the parties still disagree, either the client or builder can open a milestone dispute and submit supporting evidence. Opening a dispute locks settlement, so funds are not released automatically. PactAgent can analyze the evidence and provide a recommendation, but that recommendation is advisory and still requires human acknowledgement.

The current dispute flow supports three outcomes: full payout to the builder, refund to the client, or a split settlement. Refunds and split settlements require consent from both parties. Full payout ultimately requires confirmation from the client reviewer.

So, in the current implementation, there is an escalation and evidence flow, but there is not yet a built-in independent reviewer committee making a binding ruling. Resolution is handled by the agreement participants and the authorized reviewer/application, with PactAgent assisting rather than acting as the final arbitrator.

[Ajay]

Hi everyone,

I’d like to share a new developer update on PactAgent and get feedback from the Nervos CKB community.

PactAgent has moved from being a single end-user agreement/payment app to a reusable, app-scoped agreement and escrow infrastructure layer, exposed via a versioned /v1 API, API keys, signed webhooks, workers, and a developer console. The original product still exists as a legacy surface (/api), so nothing was thrown away – it’s just no longer the core.

Why this change

PactAgent originally behaved as its own product: wallet auth, agreement pages, grant/bounty imports, profiles, proof flows, reviewer interactions, and settlement UI were all tightly coupled to a built-in interface and legacy /api routes. External systems were never really treated as customers of the backend.

The goal of this transition was to turn that backend into neutral infrastructure that other applications can build on top of — without forcing them to inherit PactAgent’s original UI, marketplace, DAO, bounty, or reputation behavior.

1. Architecture: from app to platform

• Every external application is now represented as an App/Project tenant.

• API keys resolve each request to a single appId, which scopes all data and actions.

• Agreements, milestones, escrows, proofs, reviews, disputes, transactions, events, webhooks, idempotency keys, and audit logs are all owned by that tenant boundary.

• Neutral primitives replaced assumptions baked in for a specific marketplace/DAO/bounty product.

2. Tenant boundary (Apps/Projects)

• Apps have identity, slug, owner, environment, status, default currency/network.

• Sandbox and production environments are separated.

• appId is enforced at the database layer via compound keys/foreign keys – cross-tenant access is blocked structurally, not just in application logic, and covered by negative tests.

• A pre-migration tenant-integrity audit was added for legacy data.

• Genuinely global access requires separate internal admin authorization, not app credentials.

3. Auth: API keys for integrators

• Sandbox keys: pa_test_ prefix. Production keys: pa_live_.

• Raw keys are shown once, at creation. Only a hash + display-safe prefix are stored afterward.

• Keys carry scopes (RBAC) restricting which operations they can perform, including privileged proof-review actions.

• Supports X-API-Key header and bearer-token auth.

• Internal /v1/admin auth is fully separated from app API keys, with allowlisting and audit logging.

4. The versioned /v1 API

• New dedicated entrypoint, modular routing, standard JSON envelopes, structured error codes, request IDs/tracing, validation middleware, cursor/limit pagination.

• Full OpenAPI spec at /openapi.json, interactive docs at /docs.

• /health and /ready endpoints, plus an API lifecycle/compatibility policy for integrators.

Covers: apps & keys, agreements & milestones, escrows & transactions, proofs & reviews, disputes, lifecycle events, webhook endpoints & deliveries, audit logs, and internal admin monitoring.

5. Modular backend refactor

Domain logic moved into modules under server/src/modules (apps, keys, auth, agreements, milestones, escrows, transactions, proofs, reviews, disputes, events, webhooks, audit logs, admin, docs, health), each split into controllers/services/repositories/models/validation/events/routes/state machines. Legacy services were kept only where still needed. This is documented as a modular monolith – not prematurely split into microservices.

6. Agreements & milestones

• App-scoped creation/listing/lookup, acceptance, funding transitions, cancellation.

• External reference IDs + metadata for integrator correlation.

• Explicit lifecycle states with transition validation.

• Milestone totals are enforced against agreement totals.

• Amounts use integer-string handling to avoid floating-point errors, with exact rounding/conversion rules and quote timestamps.

• Funded agreement/milestone terms are bound via digests to on-chain CKB escrow data and become immutable – no inserting, deleting, or materially changing terms after funding begins.

7. Escrow & settlement

• New escrow adapter interface decouples lifecycle orchestration from any single settlement backend.

• Sandbox/mock adapter for testing, manual adapter for controlled ops, and a CKB adapter boundary retaining the real on-chain escrow lock.

• Escrow state machine with guards against invalid terminal transitions (no release after refund or vice versa).

• Release requires approved proof or an appropriate dispute resolution.

• Multi-milestone settlement fixed so one released/refunded escrow no longer incorrectly terminates the whole agreement.

• Release/refund reworked into reserve → external execution → finalization stages, with external calls kept outside long DB transactions, plus idempotency controls against duplicate settlement.

• Failed adapter operations are recorded as auditable states, with explicit settlement readiness/reconciliation reporting.

8. Proofs, reviews & disputes

• App-scoped proof submission/listing/lookup with evidence-link validation.

• Approved / rejected / needs-changes review decisions, tied to milestone and agreement state, gated by dedicated key scopes.

• Disputes: creation, listing, lookup, and resolution via release, refund, split, or cancellation, with their own state machine, events, and audit trail. Settlement is blocked while a dispute is unresolved.

• A 5-day manual-review inactivity deadline was added, with reviewStartedAt/reviewDeadlineAt tracked and surfaced in the API/UI.

• A worker auto-approves after the deadline only if proof is ready and the client hasn’t messaged, requested info, or opened a dispute – and this is still bounded by the deployed CKB lock’s own signature rules, so app-level approval can’t bypass the contract.

9. Events & webhooks

• Queryable, app-scoped event stream across agreements, milestones, escrows, proofs, reviews, disputes, and deliveries.

• Full webhook endpoint management plus async delivery records (pending/delivered/failed, with response snippets, attempt counts, retry scheduling).

• HMAC SHA-256 signatures via PactAgent-Event-Id, PactAgent-Timestamp, PactAgent-Signature headers, signed payload = timestamp + "." + rawBody.

• Webhook secrets: encrypted, hashed, copy-once reveal, rotation support.

• SSRF protections: localhost/loopback/private networks, metadata addresses, unsafe protocols, DNS rebinding, mixed DNS results, redirects, delivery-time revalidation, plus production HTTPS/egress requirements.

10. Idempotency & concurrency

• App-scoped idempotency keys on agreement creation, escrow creation, proof submission, release, refund, and dispute resolution.

• Switched from check-then-act to reservation before side effects.

• Same key + same body → replayed response. Same key + different body → conflict.

• DB constraints, conditional writes, and configurable transaction timeouts back this up, with concurrency tests across creation, settlement, retries, and worker processing.

11. Audit, security & abuse protection

• App-scoped audit logs with chain verification and retention/archival.

• Security headers, production CORS validation.

• Rate limits by IP, tenant, API key, high-risk action, and WebSocket, with explicit fail behavior if Redis is unavailable.

• Size limits on untrusted inputs, sensitive-field redaction in logs/telemetry, sanitized public config (no leaking secrets, treasury details, node URLs, lock metadata).

• Provider timeout/retry/concurrency/circuit-breaker controls.

• Production environment validation fails closed if required security config is missing.

• Tests confirming public events don’t leak private agreement data.

12. Worker & runtime separation

• Background automation is no longer an embedded side effect of the API server – it now runs as independent worker processes with selectable roles (settlement, webhooks, AI processing).

• Atomic job claiming via DB locks, leases with renewal/expiry, execution deadlines, bounded concurrency, retry backoff, graceful shutdown, stale-lock recovery, dead-letter listing with audited replay, heartbeats, and metrics.

13. Developer console

• New console at web/src/app/console: project/environment selection, API key management (create, scope, copy-once reveal, masking, revocation), and app-scoped views for everything (agreements, milestones, escrows, transactions, proofs, reviews, disputes, events, audit logs, webhooks, deliveries).

• Sandbox workbench for creating agreements/milestones, funding mock escrow, submitting proof, reviewing, and releasing/refunding – all without touching real funds.

• Frontend fully updated for /v1 (API helpers, scopes, event names, signing headers, routing to docs/OpenAPI/health).

14. Documentation

• Docs rewritten around PactAgent as programmable agreement infrastructure: apps, keys, scopes, agreements, milestones, escrow, proofs, reviews, disputes, events, webhooks, idempotency, sandbox mode, security.

• Full OpenAPI spec, integrator quickstart, changelog, and API lifecycle policy.

• Architecture decision records (tenancy, modular boundaries, durable jobs, settlement state, DB enforcement) plus production runbooks (config, secrets, audit retention, resilience, providers, observability, DR, releases, SLOs, workers, supply chain).

15. Deployment, observability & CI

• Root workspace automation for build/lint/test/schema/OpenAPI/audit checks.

• Docker images, dev + production Compose stacks, Kubernetes manifests (migrations, API, workers, web, dependencies) with resource limits, security contexts, probes, and graceful termination.

• Commit-addressed container delivery replacing mutable host deploys, migration-before-rollout sequencing, smoke tests, health-gated rollback.

• Structured logs/traces/request IDs, metrics across API/DB/queue/worker/settlement/provider/webhook/WebSocket, OpenTelemetry collector config, version-controlled dashboards, Prometheus alerts.

• Bounded/resumable retention for idempotency records, webhook data, events, jobs, and audit archives, plus backup/restore verification and disaster-recovery exercises.

• CI gates across build/lint/tests/migrations/OpenAPI/contracts/audits/deployment/observability assets, secret & container scanning, Dependabot, license policy enforcement, deterministic lockfiles, and CODEOWNERS.

16. Legacy product separation

• Infrastructure lives under /v1; the original product stays under /api, gated by ENABLE_LEGACY_PRODUCT_API and required to be disabled in staging/production.

• Primary UI and docs now point integrators to the console and /v1 API.

17. Verification

Extensive test coverage was added: state machines, scopes, API keys, signing, retries, security rules, amounts, resilience, redaction, tenancy, rate limits, deadlines, retention, workers; DB-level tenant isolation, migration compatibility, idempotency, concurrency, escrow settlement, multi-milestone behavior, adapter failures; webhook SSRF/redirect/DNS-rebinding/signature/retry tests; WebSocket auth/origin/disclosure/heartbeat tests; health/readiness tests; plus deployment, dependency, license, and backup/restore validators.

---

Result

PactAgent now provides:

• A strict App/Project tenant boundary

• Scoped, revocable API keys

• A versioned, documented /v1 API

• Agreement, milestone, proof, review, dispute, escrow, and transaction primitives

• Lifecycle state machines, events, and signed webhooks

• Idempotent, concurrency-safe settlement

• Sandbox adapters alongside a real CKB settlement boundary

• A developer console and sandbox workbench

• Separate API and worker runtimes

• Security, audit, observability, deployment, retention, and recovery controls

• Clean isolation of legacy end-user product behavior

In short: PactAgent can now serve as backend infrastructure for multiple agreement-driven products, not just the original PactAgent experience.