# Feeds update flow

Source: https://docs.settlemint.com/docs/architecture/flows/feeds-update-flow
End-to-end lifecycle of publishing, validating, and consuming feed values in
DALP, covering both issuer-signed scalar feeds and Chainlink adapter reads.




## System context [#system-context]

Feeds update flow connects signed price or oracle data to on-chain validation, indexing, and consumer reads. Feed contracts validate the submitted value before storage, and downstream consumers read either direct contract state, Chainlink adapter output, or indexed API data.

<Mermaid
  chart="`
stateDiagram-v2
  [*] --> ValuePrepared: issuer signer or oracle operator prepares value
  ValuePrepared --> Submitted: update transaction enters signing flow
  Submitted --> Validated: feed contract checks signer, time, drift, positivity, and decimals
  Validated --> Stored: accepted value stored by history mode
  Validated --> Rejected: validation fails
  Stored --> Indexed: Chain Indexer records event
  Indexed --> Consumed: API, Asset Console, contract, or adapter reads value
  Rejected --> ValuePrepared: submit corrected value
  Consumed --> [*]
`"
/>

## Related [#related]

* [Feeds system](/docs/architecture/components/infrastructure/feeds-system) — registry, feed types, trust model
* [Issuer-Signed Scalar Feed](/docs/architecture/components/capabilities/issuer-signed-scalar-feed) — configuration and signing model
* [Signing flow](/docs/architecture/flows/signing-flow) — foundational transaction signing sequence

***

## Flow overview [#flow-overview]

* An authorized party (issuer signer or oracle operator) produces a new value for a registered feed
* The value is submitted as an on-chain transaction to the feed contract
* The feed contract validates the update against its configured rules (signature, timestamp, drift, positivity, decimals)
* On success, the feed emits events and stores the value according to its history mode
* The chain indexer picks up the events and updates the off-chain database
* Consumers read values on-chain (direct contract call or via Chainlink adapter) or off-chain (via Unified API / Asset Console)

***

## Happy path sequence [#happy-path-sequence]

1. **Update origin** — Issuer signer prepares a signed value (value + timestamp + signature) or an oracle operator submits an aggregated data point
2. **Transaction submission** — The signed update is submitted to the feed contract via the Execution Engine and Transaction Signer
3. **Signature verification** — Feed contract recovers the signer and checks it matches the authorized issuer address
4. **Timestamp / nonce check** — Ensures the update is newer than the last accepted value (prevents replay)
5. **Drift validation** — Compares the new value against the previous value; flags as outlier if the change exceeds the configured drift allowance
6. **Positivity check** — Rejects zero or negative values
7. **Decimals consistency** — Ensures the value aligns with the feed's fixed decimal configuration
8. **History mode handling** — Stores the value according to the configured mode:
   * Latest-only: overwrites the single stored value
   * Bounded: appends and prunes if limit exceeded
   * Full: appends to permanent history
9. **Event emission** — Feed contract emits a value-updated event with value, timestamp, sequence number, and outlier flag
10. **Indexer pickup** — Chain indexer detects the event and writes the new value to the off-chain database
11. **On-chain consumer read** — Any contract calls the feed directly (or via a Chainlink adapter) to get the latest value
12. **Off-chain consumer read** — Asset Console and Unified API query the indexed data for display and API responses

***

## Trust & validation checkpoints [#trust--validation-checkpoints]

| Checkpoint             | What is verified                                               | Provider       | Failure outcome                                   |
| ---------------------- | -------------------------------------------------------------- | -------------- | ------------------------------------------------- |
| **Signature**          | Signer matches authorized issuer                               | Feed contract  | Transaction reverts; value rejected               |
| **Timestamp ordering** | New timestamp > last accepted timestamp                        | Feed contract  | Transaction reverts; replay prevented             |
| **Drift allowance**    | Value change within configured percentage                      | Feed contract  | Value accepted but flagged as outlier             |
| **Positivity**         | Value > 0                                                      | Feed contract  | Transaction reverts; zero/negative rejected       |
| **Decimals**           | Value precision matches feed configuration                     | Feed contract  | Transaction reverts; format mismatch              |
| **Authorization**      | Caller holds required role (Feeds Manager or token governance) | FeedsDirectory | Registration/replacement reverts; read unaffected |

***

## Failure modes [#failure-modes]

* **Stale feed** — No updates for an extended period. Consumers read the last-known value. Compliance modules may block transfers if staleness exceeds acceptable thresholds.
* **Paused feed** — Issuer deliberately stops publishing. Same consumer impact as stale, but intentional. Monitoring should distinguish paused from stale.
* **Key compromise** — Issuer's signing key is compromised. Attacker can publish arbitrary values. Mitigation: Feeds Manager removes the compromised feed from the directory and registers a replacement.
* **Chain reorg** — A submitted update may be reverted by a chain reorganization. The indexer must handle reorgs by re-processing affected blocks.
* **Invalid signature** — Malformed or unauthorized signature. Transaction reverts on-chain; no value is stored.
* **Drift exceeded** — Value accepted but flagged as outlier. Consumers with strict tolerance may ignore outlier-flagged values.
* **High volume** — Rapid consecutive updates may cause nonce conflicts in the Transaction Signer. The nonce manager serializes submissions to prevent conflicts.
* **Adapter target missing** — Chainlink adapter resolves to a removed feed (directory returns zero address). Adapter call reverts; external integrations see failure.
* **Indexer lag** — Off-chain database temporarily behind on-chain state. Asset Console and API show slightly stale data until indexer catches up.

***

## Operational signals [#operational-signals]

| Signal               | Source         | Monitoring use                                     |
| -------------------- | -------------- | -------------------------------------------------- |
| `FeedValueUpdated`   | Feed contract  | Track update frequency and detect staleness        |
| `OutlierFlagged`     | Feed contract  | Alert on drift-exceeded events                     |
| `FeedRegistered`     | FeedsDirectory | Audit trail for feed lifecycle changes             |
| `FeedReplaced`       | FeedsDirectory | Detect feed swaps; verify adapter resolution       |
| `FeedRemoved`        | FeedsDirectory | Alert consumers that a feed is no longer available |
| Indexer block height | Chain indexer  | Detect indexer lag by comparing to chain head      |

**Alert conditions:**

* No `FeedValueUpdated` event for a feed within its expected update cadence
* `OutlierFlagged` events exceeding a threshold count within a time window
* Indexer lag exceeding acceptable staleness for off-chain consumers

***

## Change impact [#change-impact]

| Change                         | What happens                                                     | Who is affected                     |
| ------------------------------ | ---------------------------------------------------------------- | ----------------------------------- |
| **Feed replaced in directory** | Adapter automatically resolves to new feed; consumers unaware    | External integrations (transparent) |
| **Feed removed**               | Discovery returns zero address; consumers must handle gracefully | All consumers of that subject+topic |
| **Drift allowance changed**    | Requires deploying a new feed instance (config is immutable)     | Issuer operations                   |
| **History mode changed**       | Requires deploying a new feed instance                           | Consumers relying on history depth  |
| **Issuer key rotated**         | New feed instance with new authorized signer; old feed replaced  | Issuer operations, directory admin  |
| **Adapter redeployed**         | External integrations must update their pointer address          | All external consumers (breaking)   |

***

## Sequence diagram [#sequence-diagram]

<Mermaid
  chart="`
sequenceDiagram
  participant Issuer as Issuer Signer
  participant EE as Execution Engine
  participant Feed as Feed Contract
  participant Dir as FeedsDirectory
  participant Idx as Chain Indexer
  participant App as Consumer App

  Issuer->>EE: Submit signed value
  EE->>Feed: Write transaction
  Feed->>Feed: Verify signature
  Feed->>Feed: Validate timestamp, drift, positivity
  Feed->>Feed: Store value by history mode
  Feed-->>Idx: Emit FeedValueUpdated event
  Idx->>Idx: Index event to off-chain database
  App->>Dir: Query subject and topic
  Dir-->>App: Feed contract address
  App->>Feed: Read latest value
  Feed-->>App: Value, signature, and timestamp

`"
/>

**Question answered:** What steps does a feed value go through from issuer to consumer?

**Participants:** Issuer Signer and Consumer App are external actors; Execution Engine, Feed Contract, FeedsDirectory, and Chain Indexer are [infrastructure components](/docs/architecture/components/infrastructure).

**Key takeaways:**

1. All writes go through the Execution Engine for reliable transaction management
2. Validation is enforced on-chain — invalid updates never reach storage
3. Consumers discover feeds through the directory, never hard-coding feed addresses

***

## See also [#see-also]

* [Feeds system](/docs/architecture/components/infrastructure/feeds-system) — registry, Chainlink adapter, trust model
* [Issuer-Signed Scalar Feed](/docs/architecture/components/capabilities/issuer-signed-scalar-feed) — configuration and signing model
* [Signing flow](/docs/architecture/flows/signing-flow) — foundational transaction signing used by feed updates
* [Chain indexer](/docs/architecture/data-availability/chain-indexer) — how events reach the off-chain database