docs/feat: treasury hold docs, backend env validation, address schema check, mainnet dry-run

[augustinemartins]

Summary

Four independent improvements across documentation, tooling, and scripts.

---

Commit 1 — docs: document on hold and escalate hold endpoints

Files: docs/api-reference.md (created), docs/contract-interaction-guide.md (created)

The backend routes /api/treasury/on-hold-settlements, /api/treasury/release-hold, and /api/treasury/escalate-hold were missing from the API reference. This commit:

• Creates docs/api-reference.md with full documentation for all treasury endpoints, including the three missing ones. Each entry includes request/response JSON examples, parameter tables, and error-response tables.
• Creates docs/contract-interaction-guide.md documenting the hold_settlement, release_hold, and raise_dispute contract entrypoints (parameters, emitted events, error codes), with bidirectional cross-links between the API reference and the contract guide.

---

Commit 2 — feat: extend env validation script for ts backend

Files: scripts/validate_backend_env.sh (created), docs/dev-environment.md (updated)

The existing environment validation was scoped only to contract deployment variables. This commit:

• Adds scripts/validate_backend_env.sh which validates MONGO_URI, REDIS_URL, and WEBHOOK_SECRET (required) and the three contract IDs (optional, enforced with STRICT=1). Error-reporting style matches the existing deployment scripts.
• Validates WEBHOOK_SECRET length (must be ≥ 32 chars).
• Accepts an optional env file path as its first argument.
• Updates docs/dev-environment.md with a validation step in the Backend setup section, including a variable reference table.

---

Commit 3 — feat: validate exported addresses against schema

Files: scripts/export_deployed_addresses.sh (updated)

artifacts/addresses.json is gitignored and consumed by other tooling. A broken export could silently produce a malformed file. This commit adds a Python-based schema validation step immediately after the write:

• Confirms the output is a valid JSON object with a non-empty network string and a non-empty contracts array.
• Confirms every contract entry has non-empty name and address string fields.
• Confirms all three required contracts (invoice, treasury, compliance) are present.
• Emits [schema-validation] FAIL: <reason> to stderr and exits 1 on any violation.

---

Commit 4 — feat: add dry run mode to mainnet deploy script

Files: scripts/deploy_mainnet.sh (updated)

The mainnet deploy script previously only printed a refusal message. This commit adds a --dry-run flag:

• --dry-run prints network config, signing authority, contract addresses, and a numbered 9-step planned action list — formatted to paste directly into a deployment-checklist PR.
• Makes zero network-mutating calls in dry-run mode.
• Running without arguments still refuses with exit 1 and points to docs/MAINNET_DEPLOYMENT.md.

---

What was tested

Task	Verification
1	Markdown structure reviewed; cross-links checked against contract ABI
2	Script run with missing vars (exits 1), with all vars set (exits 0), and with short WEBHOOK_SECRET (exits 1)
3	Validation logic verified: valid output passes; missing contracts key fails; missing treasury entry fails
4	--dry-run exits 0 with full output; no-arg exits 1; unknown arg exits 1

Closes #268
Closes #269
Closes #270
Closes #271

[drips-wave]

@augustinemartins Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits