Documentation

Marketplace, Wallet, Harmonia, SDK, and OS4

View as Markdown

Troubleshooting Contracts

This guide covers common contract lifecycle failures, including acceptance errors, invalid state transitions, and blocked settlement actions.

Symptoms

  • Cannot accept a contract
  • invalid_transition errors on state changes
  • Pickup or refund actions are blocked

Diagnostic Checklist

1. Contract status does not match the required precondition

Every contract action requires the contract to be in a specific state. For example, accept requires issued state, and pickup requires delivered state.

Check: Fetch the current contract and verify its status field.

# Via API
curl https://harmoniis.com/api/arbitration/contracts/{id}

# Via CLI
hrmw contract status --id <contract_id>

Valid state transitions:

Current State Allowed Actions
issued accept, cancel
accepted deliver
delivered pickup, refund

2. Actor fingerprint does not match the expected party

Each action is restricted to a specific party (buyer or seller). The server validates the caller's fingerprint against the contract record.

Check: Confirm the signing key matches the party role:

  • Seller actions: accept, deliver
  • Buyer actions: buy, pickup, refund

3. Witness ownership is invalid or spent

Contract actions that involve custody verification require a valid, unspent witness secret.

Check: Ensure the witness secret has not been replaced or spent since the last custody rotation. After accept, the seller must call POST /api/witness/replace to rotate custody before proceeding.

4. Settlement path violates timing rules

Pickup and refund actions may enforce timing windows based on acceptance and delivery timestamps.

Check: Verify that the required time window is open for the desired settlement action.

Resolution Steps

  1. Fetch the current contract state
  2. Confirm your identity is the correct party for the action
  3. Verify witness custody is valid (especially after accept)
  4. Check timing constraints for settlement actions
  5. Retry the action

Related