Escrow and Conditional Payments

Payment Guarantees for Agent Commerce

Escrow separates a payment commitment from its final distribution. A buyer or agent funds a dedicated escrow account, a named beneficiary captures funds under the agreement, and a named arbiter resolves disputes. Marketplaces, service purchases, procurement, and milestone contracts use the same protocol lifecycle.

The escrow module stores the agreement terms and lifecycle. Every movement of value uses the shared 402LXP transfer mechanism, including funding, beneficiary payments, refunds, and dispute splits. The account namespace is agent:<did>:escrow:<id>.

Define an Escrow

The terms hash commits to the agreement. Applications verify delivery, evidence, or milestones against that agreement before requesting an authorized capture; hashing terms does not itself evaluate a real-world condition.

Lifecycle and Actions

Authority and Deadlines

The beneficiary or an owner principal acting through a delegated capability authorizes capture. The owner authorizes release. Either owner or beneficiary can open a dispute while the hold is active and the dispute deadline has not passed. Only the designated arbiter resolves the dispute.

Captures fail at or after a nonzero expiry, even before a timeout sweep changes the recorded state. Batch maintenance processes due escrow deadlines using the batch timestamp. Disputed holds do not follow the ordinary timeout refund path; they require resolution.

Milestone Payment Workflow

1. Agree on the asset, owner, beneficiary, arbiter, deadlines, and delivery conditions.
2. Open and fund the escrow for 1,000 base units.
3. After the first milestone, partially capture 300 units. The beneficiary receives 300 and 700 remain locked.
4. On completion, capture the remaining 700. Alternatively, release the unused 700 to the owner.
5. If a dispute is opened before the deadline, submit evidence to the arbiter and resolve the remaining balance.

Dispute Split Example

A resolution specifies the beneficiary share in basis points from 0 to 10,000. With 700 units remaining and a 6,000 basis-point award, the beneficiary receives 420 and the owner receives 280. Earlier captures remain paid. The beneficiary amount rounds down to an integer base unit; the owner receives the remainder, preserving the complete escrow balance.

beneficiary = floor(remaining_balance × beneficiary_basis_points / 10000)
owner       = remaining_balance - beneficiary

Protocol Reference

Escrow is module 2. Activity payloads use fixed-width IDs and integer amounts; they are protocol activities rather than EVM contract method names.

Retries and Failure Handling

Capture, release, timeout, and resolution carry a nonzero idempotency key. Preserve that key when retrying the same operation. Keys bind to the escrow and operation context; reusing one for a different payment is rejected. Track the returned receipt and final state before advancing a business workflow.

Handle expired holds, disputed holds, unauthorized capture, and capture amounts above the remaining balance as distinct failures. A partial capture cannot equal the entire balance: use full capture instead. Out-of-range dispute splits are rejected.

Related Guides

• Continuous and metered payments
• Protocol modules
• Build with the SDK