From intent to finality

Suppose a participant submits a transaction for a Polymarket contract. The service may observe a candidate before a block, inspect the transaction’s receipt, and later reassess whether its inclusion remains canonical. These are distinct observations; every transaction does not have to pass through each one in order.

Pending: a possible participation

fill.intent represents a supported, admitted preliminary participation. It describes signed intent and requested values, but contract state can change before execution. The transaction may not be included, or it may revert. Even a precisely decoded calldata amount is still requested, not actual.

The order owner, signer, and transaction sender may be different addresses. A relayer or operator sending a transaction does not become the order owner merely because it submitted the transaction.

Receipt: what happened in this transaction

transaction.included records a successful result established from a complete receipt. A normalized fill.execution carries actual values when the receipt has a supported interpretation. Check normalizationStatus; do not manufacture an execution from a successful transaction status alone.

transaction.reverted records a failed transaction and does not create fills. A later reorg of a successful inclusion is a separate condition, not a revert.

The receipt can be observed first. In that case an execution may exist without a previously observed intent, and the relationship remains unavailable rather than being inferred from a transaction hash alone.

Inclusion: is this occurrence still canonical?

An assessment belongs to a specific inclusion occurrence. If the same transaction is included again in a different block, that is a different occurrence. Keep the correction tied to the prior occurrence; do not silently rename it or count both as independent final execution volume.

When the outcome is unknown

horizon_expired_unknown means observation ended without an established outcome; it does not mean “cancelled.” A transaction with the same nonce is a competing candidate, but observing one does not by itself prove that the earlier transaction was finally replaced. A later receipt may refine the earlier assessment.

Consumers must be able to start from a receipt, receive corrections, and preserve an explicit unknown state. Do not require pending → included → finalized for every object.

Next: identities, corrections, and event payloads.