Copy page

Product APIs

Contract Vault

The current contract vault is now the first marketplace contract spine. It stores wallet-linked contracts with opportunity references, participant roles, milestone progress, evidence counts, payment-control state, and anchoring state. It now also exposes contract versions, signature receipts, structured commitments, extraction runs, and append-only history events: version proofs store SHA-256 hashes for exact contract content, signature receipts roll up the version signature state signer by signer, commitments store extractable contract points such as "build five restaurants" with progress like 0 / 5, and events preserve the operator/extractor/payment/anchor timeline around those objects.

Current model

A current contract-vault record includes:

• Wallet holder link by phone or end-user id.
• Contract reference.
• Title and counterparty.
• Optional programme and opportunity reference.
• Participant role.
• Status.
• Currency and value.
• Milestone progress such as 0 / 5.
• Next milestone label/date.
• Control profile.
• Payment-control status.
• Anchoring status.
• Evidence count.

Version proofs are stored separately from the contract row so a signed document, draft, upload, extraction run, and future anchoring adapter can all refer to one exact content hash. Anchoring events can now be posted against those version proofs by a vault, notary, blockchain, or batch worker. The endpoint records an append-only anchor_recorded event and rolls the contract anchoringStatus forward while keeping the concrete anchoring provider replaceable. The backoffice Contract Vault page also exposes this as an operator workflow: record the returned anchor receipt, then review it in the proof anchoring section beside version proofs, signature requests, signatures, extraction runs, and contract history.

Versions include:

• Contract reference.
• Version number.
• SHA-256 content hash and proof label.
• Optional document URI or storage reference.
• Version status.
• Signature status.
• Current-version flag.
• Source: manual, upload, extracted, or imported.
• Extraction reference and signer summary.

Signature receipts are stored separately from the version proof so each required signer can be followed up independently.

Signature requests are stored before receipts. They are provider-neutral ceremony records, so HeritagePay can route later to a gateway, partner API, qualified electronic provider, wet-signature workflow, or manual follow-up without changing the contract proof model. Provider callbacks or reconciliation jobs can then update the same ceremony by provider request reference, creating the signer receipt, rolling the version signature status forward, and appending contract history events without binding the core contract vault to one signature vendor. Backoffice operators can apply that same provider-event contract manually from Contract Vault when a provider has not pushed the callback directly or an operations team needs to reconcile a provider status.

Signature requests include:

• Stable request reference.
• Contract reference and version number.
• Replaceable provider class and optional provider request reference.
• Request status, channel, signer references, callback URL, and timestamps.
• Operator notes and safe metadata.

Signatures include:

• Contract reference.
• Version number.
• Stable signer reference.
• Signer role and safe label.
• Status: pending, sent, viewed, signed, rejected, or expired.
• Method: manual, OTP, provider, wet signature upload, or qualified electronic.
• Optional proof reference and proof hash.
• Signed/rejected timestamps.

Structured commitments are stored separately from the contract row so a human operator, extraction service, vault process, or future chain anchoring process can all refer to the same measurable point.

Commitments include:

• Contract reference.
• Commitment reference.
• Title and optional clause detail.
• Category.
• Unit label.
• Expected and completed quantity.
• Progress such as 0 / 5.
• Status.
• Verifier reference.
• Due date.
• Source: manual, extracted, or imported.
• Evidence policy.

Contract history events are stored separately from contracts, versions, and commitments. They provide the audit-friendly timeline that later extraction, signature, payment gateway, vault, and chain anchoring modules can all append to without owning the contract row.

Events include:

• Contract reference.
• Stable idempotency event reference.
• Event type, such as commitment_progressed or anchor_recorded.
• Title and optional detail.
• Optional linked commitment reference.
• Optional linked version number.
• Source: manual, system, extracted, imported, gateway, or anchoring.
• Actor reference.
• Occurred-at timestamp.

Extraction runs are stored as side-service outputs. The core API does not run AI extraction itself; it accepts a signed extractor/import result, stores the run metadata, creates proposed commitments with source=extracted, and appends history events. Operators can then accept or reject the extraction run from backoffice; accepted runs expose how many proposed commitments are now accepted for follow-up.

Extractions include:

• Contract reference.
• Stable extraction reference.
• Optional source contract version number.
• Optional document URI or storage reference.
• Engine reference.
• Status: received, proposed, accepted, rejected, or failed.
• Summary, notes, and structured proposal metadata.
• Proposed commitments and accepted commitment count.

This lets mobile and backoffice show linked marketplace contract state while keeping the extraction worker runtime, external signature provider, and blockchain anchoring as separate replaceable modules.

Marketplace evidence now carries attachment policy metadata: storage provider, object key, byte size, attachment status, visibility, retention policy, and verification timestamp. Approved file evidence must include a URI and SHA-256 checksum; note-only evidence may be approved without a file attachment. The actual upload adapter remains replaceable.

Marketplace payment controls now have a separate payment execution ledger. Controls decide whether a release is allowed; executions record the handoff to a replaceable gateway, provider, Blnk adapter, partner, or manual settlement path. The execution record carries provider, provider execution reference, attempt number, status, timestamps, response code/message, and safe metadata. This is enough for operators to follow what happened after approval while keeping concrete callbacks and live settlement adapters modular.

API surfaces

• End-user view: GET /contract-vault/my returns scoped contracts plus the current signed version proof and tracked commitments visible to the user.
• Operator query: GET /internal/contract-vault
• Operator store: POST /internal/contract-vault
• Contract versions: GET|POST /internal/contract-vault/versions
• Contract version anchor events: POST /internal/contract-vault/versions/anchor-events
• Signature requests: GET|POST /internal/contract-vault/signature-requests
• Signature provider events: POST /internal/contract-vault/signature-requests/provider-events
• Contract signatures: GET|POST /internal/contract-vault/signatures
• Contract commitments: GET|POST /internal/contract-vault/commitments
• Contract history events: GET|POST /internal/contract-vault/events
• Contract extractions: GET|POST /internal/contract-vault/extractions
• Extraction decisions: POST /internal/contract-vault/extractions/decisions
• Marketplace programmes: GET|POST /internal/marketplace/programmes
• Marketplace opportunities: GET|POST /internal/marketplace/opportunities
• Marketplace participants: GET|POST /internal/marketplace/participants
• Marketplace assignments: GET|POST /internal/marketplace/assignments
• Marketplace milestones: GET|POST /internal/marketplace/milestones
• Marketplace evidence: GET|POST /internal/marketplace/evidence
• Marketplace payment controls: GET|POST /internal/marketplace/payment-controls
• Marketplace payment executions: GET|POST /internal/marketplace/payment-executions
• Marketplace provider events: POST /internal/marketplace/payment-executions/provider-events

Remaining marketplace target

The remaining target is richer than the current contract-vault spine. It still needs concrete provider verification adapters, an external anchoring worker, and gateway-specific live settlement adapters.

Example: if a contract says "build five restaurants", the admin surface stores structured commitments such as 0 / 5, and the mobile/end-user response now exposes those commitments with the current signed version proof. Marketplace milestone rows, evidence rows, payment-control instructions, and version hashes remain separate objects. Contract history events now give those objects one follow-up timeline. Extraction runs can now post proposed commitments and append events automatically, and operators can accept or reject the extractor output after review. Signature receipts now enforce version rollup inside the core API. Payment executions now track provider handoff and settlement state after a control is approved. If the payment control is linked to a contract, the execution write and provider-event update both append payment_execution_recorded history events with provider, provider reference, execution status, amount, and safe provider response detail. Signature provider events now do the same for signature requests: callbacks reconcile by provider request reference, record the signer receipt, and roll the signed version state forward. Backoffice operators can apply payment provider-event reconciliation from Marketplace and signature provider-event reconciliation from Contract Vault when callbacks need manual review. The next step is to connect these provider-neutral callback boundaries to selected external verification adapters. Anchoring events now provide the same modular intake for a future vault, notary, or blockchain worker: the core stores the event and status, while the adapter that actually writes to a chain or vault can be swapped. Operators can record those receipts from the backoffice once a worker or provider has returned a stable anchor reference.

Modular extraction

Document extraction should remain a side service. The core backend should accept structured contract records and hashes, while the extractor can be replaced without rewriting wallet or admin flows.

See Marketplace Architecture for the target bounded contexts and implementation order.