docs: Proposal for comprehensive developer documentation

[HusseinAdeiza]

Summary

The arc-escrow repository currently has a solid README but lacks comprehensive documentation for contributors, troubleshooting, and architecture understanding. This creates barriers for developers looking to contribute, understand the system design, or debug setup issues.

Current State

What exists:

• ✅ Comprehensive README with setup instructions
• ✅ Clear environment variable documentation
• ✅ Security considerations mentioned

What's missing:

• ❌ No CONTRIBUTING.md (contribution guidelines)
• ❌ No docs/ folder (centralized documentation)
• ❌ No architecture documentation with system diagrams
• ❌ No troubleshooting guide for common issues
• ❌ No deployment guide for production

Proposed Contribution

I would like to contribute comprehensive documentation covering:

1. CONTRIBUTING.md (~500 lines)

• Code of conduct
• Development workflow (branch naming, PR process)
• Code style guidelines
• Testing requirements
• Commit message conventions
• Issue reporting guidelines

2. docs/ARCHITECTURE.md (~800 lines)

• System overview and component diagram
• Data flow visualization
• Circle Developer Controlled Wallets integration
• Smart contract interaction (EIP-712 Refund Protocol)
• Supabase schema and relationships
• OpenAI validation workflow
• Webhook handling architecture
• Security model explanation

3. docs/TROUBLESHOOTING.md (~600 lines)

• Installation issues:
  • Node version compatibility (v20 vs v22 requirement)
  • npm vulnerability warnings (21 vulnerabilities on fresh install)
  • Docker setup problems
  • Supabase connection issues
• API key setup:
  • Circle API key and Entity Secret walkthrough
  • OpenAI API key configuration
  • Common authentication errors
• Runtime issues:
  • Webhook testing with ngrok
  • Database migration errors
  • Common wallet creation errors
• FAQ section

4. docs/DEPLOYMENT.md (~400 lines)

• Production deployment checklist
• Environment variable security best practices
• Vercel deployment guide
• Supabase production setup
• Circle webhook configuration for production
• Monitoring and logging setup

5. Enhanced README

• Add Quick Start section at top
• Clarify Node version requirements (tested working on v20.20.1)
• Add links to detailed docs
• Add Contributing section
• Add badges (build status, license, etc.)

Proposed Structure

arc-escrow/
├── CONTRIBUTING.md (new - ~500 lines)
├── README.md (enhanced - add ~100 lines)
├── docs/ (new folder)
│ ├── ARCHITECTURE.md (~800 lines)
│ ├── TROUBLESHOOTING.md (~600 lines)
│ ├── DEPLOYMENT.md (~400 lines)
│ ├── API.md (~300 lines)
│ └── diagrams/ (system flow diagrams)

Benefits

• ✅ Faster onboarding for new contributors
• ✅ Reduced support burden with self-service troubleshooting
• ✅ Better architecture understanding with diagrams and flow explanations
• ✅ Production-ready guidance for teams deploying this
• ✅ Clear contribution path encouraging community involvement

Implementation Plan

Timeline: 7-10 days
Estimated output: 15-20KB documentation (~2,400 lines total)

I can submit this as:

1. Single comprehensive PR (all docs at once), or
2. Multiple smaller PRs (CONTRIBUTING.md first, then docs/ incrementally)

Questions for Maintainers

1. Would you prefer one large PR or multiple smaller PRs?
2. Are there specific documentation areas you'd prioritize?
3. Any existing style guide or documentation templates I should follow?
4. Should I include Mermaid diagrams for architecture visualization?

Background

I've already:

• ✅ Cloned and analyzed the repository
• ✅ Successfully ran npm install (documented 21 vulnerabilities and Node v20 compatibility)
• ✅ Identified documentation gaps during setup
• ✅ Reviewed the codebase structure
• ✅ Tested the README instructions

Happy to provide more details on any specific area or adjust the scope based on your feedback.

---

Note: This is my first contribution to Circle's repositories. I'm committed to maintaining the high quality standards expected for enterprise-grade projects.

[osr21]

Happy to contribute — we built a similar full-stack escrow DApp on Arc Testnet and ran into several doc gaps worth capturing.

Reference implementation

osr21/arc-stablecoin-dapp — React + Express + Drizzle ORM + Solidity on Arc Testnet. Some patterns we'd want to see documented here:

---

1. Oracle condition verification (missing everywhere)

The most common escrow use case — "release funds when ETH/USD > $X" — needs an off-chain oracle check before the on-chain release(). The pattern we use:

• Store conditionType + conditionData (JSON with oracle params) in the DB at escrow creation
• Server-side endpoint GET /api/escrows/:id/oracle-check fetches live price from CoinGecko and returns { met: bool, currentValue, threshold }
• Frontend gates the Release button behind this check — if not met, shows current vs required price
• The smart contract itself has no oracle logic; the enforcement is API + UI-side

This is a pragmatic testnet pattern but the tradeoffs (trust the server) should be documented clearly alongside the alternative (Chainlink on-chain).

---

2. Clock-skew buffer for time-based releases (critical gotcha)

Time-based escrow release() calls revert if submitted even 1 block before unlockTimestamp due to block timestamp variance. We learned this the hard way — release would succeed in simulation but revert on-chain.

Fix: add a buffer (RELEASE_BUFFER_SECS = 30) and only enable the Release button / auto-release keeper after unlockTimestamp + buffer. Show a pulsing countdown badge during the buffer period so users understand the delay.

This should be a dedicated troubleshooting entry.

---

3. Keeper / auto-release architecture

For time-based escrows, nobody manually watches for expiry. We run a Node.js keeper (60s poll interval) that:

• Queries expired, un-released escrows from the DB
• Checks a ALLOWED_CONTRACTS allowlist before calling any on-chain function (prevents keeper from being weaponized)
• Calls release() on-chain using a funded keeper wallet
• Records the tx hash in the DB and activity log

A docs section on keeper security (especially the allowlist and replay protection) would be very useful.

---

4. Dispute / arbiter resolution flow

We documented the full dispute lifecycle:

1. Depositor raises dispute → status = disputed
2. Arbiter (separate wallet) reviews and calls resolve(releaseToDepositor: bool)
3. Both outcomes emit events and update state atomically

The arbiter address is set at escrow creation. Architecture docs should explain why the arbiter must be set at creation (not later) to prevent griefing.

---

Happy to open a PR with any/all of the above as a docs/ or TROUBLESHOOTING.md addition.

[HusseinAdeiza]

Thanks @osr21, really useful patterns. appreciate you sharing the war stories on the clock-skew bug especially.
Before I incorporate these, I want to check: are oracle verification, the keeper/auto-release pattern, and the dispute/arbiter flow actually implemented in arc-escrow currently, or are these patterns from your own project that you're suggesting as additions? I'll verify against the codebase either way.
Still hoping to hear from the Circle team on scope/priority (single PR vs. incremental, what to prioritize) before I commit to writing — happy to wait for that input or start with whichever piece is least controversial (e.g. the Node version / npm vulnerabilities troubleshooting entry, which is uncontroversial and already verified).

[osr21]

Hey @HusseinAdeiza — great questions, happy to clarify.

To directly answer your first question: none of those patterns are in arc-escrow today. Oracle verification, keeper/auto-release, and dispute/arbiter resolution are all patterns from our own project (osr21/arc-stablecoin-dapp) that we're proposing as doc contributions — not claiming they exist in this repo. Concretely:

Pattern	Where it lives in our project
Oracle condition verification (price feed via CoinGecko)	artifacts/api-server/src/routes/escrow.ts#L298-L340
Keeper / auto-release (off-chain CRON that calls autoRelease())	artifacts/api-server/src/lib/keeper.ts — contract allowlist, backoff, on-chain ID resolution
Dispute / arbiter flow	contracts/src/ConditionalEscrow.sol#L120-L175 + the /dispute and /release API routes
Clock-skew buffer (RELEASE_BUFFER_SECS)	Baked into the keeper tick — we found 30 s necessary on Arc Testnet due to finality lag between block timestamp and wall clock

All of it is live on Arc Testnet (chain 5042002) and battle-tested through the deployment cycle, so the gotchas in the notes are from actual debugging, not speculation.

On where to start: your instinct to open with the Node / npm vulnerabilities entry is exactly right — it's self-contained, already verified, and doesn't depend on Circle team input on scope. Happy to draft that PR first while the broader conversation plays out.

For the patterns above, I'd suggest we tackle them as a second PR (or incremental commits on the same branch) once there's signal from Circle on whether they want the doc to grow beyond troubleshooting into architecture recipes. That way nothing blocks the uncontroversial fixes.

Let me know if it would help to share the keeper or oracle source directly — I can paste the relevant snippets inline.

[HusseinAdeiza]

Sounds good. I will go ahead and open the PR for the Node version / npm vulnerabilities troubleshooting entry first, since I already have the verified details from my own install. Will keep it scoped to just that so it doesn't block on the broader architecture conversation.
For the oracle/keeper/dispute patterns agreed, let's hold those for a second PR once Circle weighs in on scope. I may take you up on pasting snippets when we get there.

[osr21]

Perfect — that sequencing makes sense. Will keep an eye out for the PR and happy to review or add context if anything from our setup is useful as a reference.

When you get to the second PR, just ping here and I can paste the keeper or oracle snippets inline — easier than cross-referencing a separate repo.