Server-Side Signer for Multi-Release Escrow Milestone Updates

[techrebelgit]

Task: Server-Side Signer for Multi-Release Escrow Milestone Updates (v1)

1) Context (What & Why)

Platforms may let end users submit milestone updates without connecting a wallet.
This task delivers a backend endpoint that signs the milestone-status update on behalf of the Service Provider role.

How it fits

• Create a multi-release escrow in the Trustless Work Backoffice.
• Assign Service Provider to a server-controlled Stellar testnet address.
• Backend flow: request unsigned XDR from the TW API → sign with the server key → submit → return tx hash & status to the caller.
  End users just fill a form (description, evidence).

🔎 Bonus (nice-to-have, optional): As step one in our modularity exploration, review OpenZeppelin Smart Accounts for Stellar to scope/guard server signing via policy (e.g., allowlisting change_milestone_status). Repo (for reference only):
https://github.com/OpenZeppelin/stellar-contracts/tree/main/packages/accounts

---

2) Functional Scope (v1)

Goal: Expose a backend endpoint that changes a milestone’s status by:

1. Requesting an unsigned transaction (XDR) from TW API.
2. Signing that XDR with the Service Provider key held by the backend.
3. Submitting the signed XDR to the network via the TW helper endpoint.
4. Returning {escrowId, milestoneId, newStatus, txHash, network, submittedAt}.

Reference API docs

• Change Milestone Status (multi-release): POST /escrow/multi-release/change-milestone-status
• Helper submission: POST /helper/send-transaction
• API Reference hub: https://docs.trustlesswork.com/trustless-work/api-reference

Required headers

• Content-Type: application/json
• x-api-key: <YOUR_TW_API_KEY>

---

3) Inputs & Output (your endpoint)

Request should include: escrowId, milestoneId, newStatus (e.g., FOR_REVIEW), and optional metadata (description, evidence URLs).
Response should include: success flag, tx hash, echo of inputs, network, and timestamp.

---

4) Non-Goals (v1)

• No UI beyond a simple form to trigger the endpoint.
• No Smart Account integration required (OZ is exploratory only).
• Testnet only (no mainnet keys or funds).

---

5) Deliverables

1. Backend endpoint implementing the flow above (any language/runtime).

2. README.md that covers:

   • Environment variables (TW API base, API key, server private key, network=TESTNET).
   • How to obtain an API key and set the Service Provider role in Backoffice.
   • How to fund the server address on testnet (XLM and required trustlines).
   • Example request/response shapes (no code), and verification steps.

3. Run logs / screenshots showing a successful milestone update (with tx hash) and verification in the Viewer or via get-escrow.

4. Security note (see checklist below).

---

6) Acceptance Criteria

• Calling the endpoint updates a milestone status on a multi-release escrow on testnet.
• The transaction hash is verifiable in the Trustless Work Viewer or by querying the API.
• The README allows a new developer to run the flow in ≤15 minutes.
• No secrets committed; endpoint is rate-limited; basic audit info is recorded.

---

7) Security Checklist (v1)

• Environment separation: testnet only, distinct config.
• Key custody: store SERVER_PRIVATE_KEY in a secret manager or .env (never in code).
• Least privilege: server address assigned only as the Service Provider for test escrows.
• Endpoint protection: rate limiting, minimal auth, and request validation.
• Audit trail: log escrowId, milestoneId, newStatus, txHash, timestamp, and (if available) request actor.
• Idempotency: repeated identical requests should return the original tx hash when applicable.

---

8) Bonus (Optional, exploratory)

• OpenZeppelin Smart Accounts (Stellar): Evaluate using a contract account for the Service Provider role to constrain what can be signed (allowlist: TW escrow contract + change_milestone_status, optional time windows/limits).

  • Repo (readme, contracts, examples):
    https://github.com/OpenZeppelin/stellar-contracts/tree/main/packages/accounts
  • Goal for this task: a brief feasibility note in your README (no implementation required).
  • If the exploration proceeds later, we’ll add a “smart” signing path behind a feature flag.

---

9) Verification / Test Plan

1. In Backoffice, create a testnet multi-release escrow; set Service Provider to your server address.

2. Ensure required trustlines exist for the escrowed asset on testnet.

3. Trigger your backend endpoint with valid escrowId, milestoneId, and FOR_REVIEW.

4. Confirm:

   • HTTP success and a tx hash in the response.
   • Viewer or API shows the milestone status For Review.

5. Negative checks:

   • Invalid milestoneId or role misassignment returns clear errors from the TW API.

---

10) Helpful Links

• Trustless Work Docs (API, lifecycle, SDK, blocks): https://docs.trustlesswork.com/
• Backoffice dApp: https://dapp.trustlesswork.com/
• Viewer dApp: https://viewer.trustlesswork.com/
• OpenZeppelin Stellar Smart Accounts (optional exploration):
  https://github.com/OpenZeppelin/stellar-contracts/tree/main/packages/accounts

[nnennaokoye]

Hi, I’m a blockchain developer with experience in Rust, Solidity, and frontend development, and I have contributed to several Stellar projects. please assign this issue to me.

[techrebelgit]

Hello @nnennaokoye go for it! Thanks!

[nnennaokoye]

Hello @techrebelgit I am experiencing difficulties creating an testnet multi-release escrow in backoffice for testing, i need help on how to go about it?

[techrebelgit]

Hello! How can I help? What is the issue?

[techrebelgit]

Hello there! Any updates on this? Thanks!