Manage Milestones

This endpoint allows the admin to add new milestones to an existing escrow and/or update the description and amount of existing milestones in a single transaction.

Requirements to use:

1. Only the entity with the admin role has permissions to execute this endpoint.

2. milestoneUpdates (editing existing milestones) is not allowed while the escrow holds funds. In that case, only newMilestones can be sent.

3. At least one of the two arrays (newMilestones or milestoneUpdates) must be non-empty.

Headers

Name	Value
Content-Type	application/json
x-api-key	<token>

New Milestone:

Name	Type	Description
description	string	Text describing the function of the milestone.
status	string (default: "pending")	Milestone status. Ex: Approved, In dispute, etc...
evidence	string (optional)	Evidence reference (URL, IPFS hash, etc.) attached to the milestone
approvalsTarget	number (optional, default: 1)	Number of distinct approvers required to consider the milestone approved. Must be ≥ 1 and ≤ the length of roles.approvers

Milestone Update

Name	Type	Description
index	number	0-based position of the milestone to update within the escrow
newDescription	string | null (optional)	New description for the milestone. Pass null to leave unchanged

Open API

Add new milestones and/or edit existing milestone descriptions

post

Single endpoint that ADDS new milestones (newMilestones) and EDITS descriptions of existing ones (milestoneUpdates) in one atomic transaction. At least one of the two arrays must be non-empty. Description-only updates are forbidden while the escrow holds funds. Admin signs.

Authorizations

x-api-key

x-api-keystringRequired

Body

application/json

contractIdstringRequired

Deployed v2 escrow contract (C...).

Example: CDHAZ2RTE2MDHYQQ7NATF5IVKIFVGLX6FHJ66OPK6MUXBSTRRXFXJ6QB

adminstringRequired

Admin wallet — signs the transaction.

Example: GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN

Responses

200

Unsigned XDR built successfully.

application/json

unsignedXdrstringRequired

Base64-encoded unsigned XDR. Sign it with the appropriate wallet and submit to Soroban / Horizon to execute the operation on-chain.

Example: AAAAAgAAAAAtWsgedQ...AAAAAQAAAAA=

txHashstringRequired

SHA-256 hash of the prepared transaction. NOTE: it only matches the executed transaction if you sign the XDR exactly as returned — re-preparing (re-simulating) it changes the hash. Prefer contractId for correlation when present.

Example: b1946ac92492d2347c6235b4d2611184a8d53f7a8e6e9b4f0c79a2b30e5c4f3a

contractIdobject · nullableOptional

Deploys only: the address (C…) the new escrow contract WILL have once this transaction executes — known upfront because the service generates the deploy salt. Track your escrow with it (e.g. GET /escrows/:contractId) as soon as the transaction lands; it is stable even if your wallet/SDK re-prepares the transaction.

Example: CAAQCAIBAEAQCAIBAEAQCAIBAEAQCAIBAEAQCAIBAEAQCAIBAEAQC526

400

Request body or query params fail schema validation (wrong type, missing required field, unknown property).

application/json

401

Missing, malformed, expired, revoked or invalid API key.

application/json

403

API key is valid but does not have the role required for this operation.

application/json

422

Payload is well-formed but a business rule rejects it (e.g. amount out of range, role not allowed for this user).

application/json

500

Unexpected server-side failure. Use the traceId to look up the incident in server logs or contact support.

application/json

post/escrow/single-release/v2/manage-milestones

HTTPcURLJavaScriptPython

POST /escrow/single-release/v2/manage-milestones HTTP/1.1
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 339

{
  "contractId": "CDHAZ2RTE2MDHYQQ7NATF5IVKIFVGLX6FHJ66OPK6MUXBSTRRXFXJ6QB",
  "admin": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
  "newMilestones": [
    {
      "description": "Phase 1 — UI design delivery",
      "status": "pending",
      "approvalsTarget": 1
    }
  ],
  "milestoneUpdates": [
    {
      "index": 0,
      "newDescription": "Phase 1 — UI design delivery (revised)"
    }
  ]
}

{
  "unsignedXdr": "AAAAAgAAAAAtWsgedQ...AAAAAQAAAAA=",
  "txHash": "b1946ac92492d2347c6235b4d2611184a8d53f7a8e6e9b4f0c79a2b30e5c4f3a",
  "contractId": "CAAQCAIBAEAQCAIBAEAQCAIBAEAQCAIBAEAQCAIBAEAQCAIBAEAQC526"
}

What this Endpoint returns?

This endpoint returns the transaction unsigned so that the transaction can be signed by means of a customer wallet.

Use Example:

import axios from "axios";

  const http = axios.create({
    baseURL: "https://dev.api.trustlesswork.com",
    timeout: 10000,
    headers: {
      "Content-Type": "application/json",
      "x-api-key": your_api_key,
    },
  });

  export const useExample = async () => {
      // Get the signer address
      const { address } = await kit.getAddress();

      const response = await http.post(
        "/escrow/single-release/v2/manage-milestones",
        {
          // body requested for the endpoint
        },
      );

      // Get the unsigned transaction hash
      const { unsignedTransaction } = response.data;

      // Sign the transaction by wallet
      const { signedTxXdr } = await signTransaction(unsignedTransaction, {
        address,
        networkPassphrase: WalletNetwork.TESTNET,
      });

      // Send the transaction to Stellar Network
      const tx = await http.post("/stellar/submit-transaction", {
        signedXdr: signedTxXdr,
      });

      const { data } = tx;

      return data;