docs: document contract architecture and failure scenarios by rjan90 · Pull Request #430 · FilOzone/filecoin-services

rjan90 · 2026-02-25T10:08:20Z

Towards: #361

Addressing/trying to answer Done criterias 1 and 2:

Document the current relationship/coupling between various contracts.

For each of the main components (PDP Verifier, Filecoin Pay, and Filecoin Warm Storage Service) answer, "If there were a flaw in *this* piece, what then?"

Documents the contract relationship/coupling in FWSS: system diagram, contract inventory table, upgrade mechanism, immutable reference coupling, and cross-contract data flows
Adds failure scenario analysis for each contract, identifying when a simple implementation upgrade is sufficient vs. when it requires broader changes (new proxy, coordinated upgrades, or state migration)
Migration strategy details left as TODOs per comment here: Document Contract Relationship and Migration Strategy #361 (comment), this PR focuses on the architectural framing.

docs: document contract architecture and failure scenarios

fix: align edges of diagram correctly

chore: add links to USDFC token/contracts

BigLep

Generally seems good to me. I'll give it a shipit once its clear that we're talking about "StateView" correctly.

SPEC.md

BigLep · 2026-02-25T22:33:57Z

SPEC.md

+
+### Upgrade Mechanism
+
+FWSS, PDPVerifier, and ServiceProviderRegistry each implement the same **two-step announce-then-upgrade** pattern. The owner first calls `announcePlannedUpgrade(PlannedUpgrade)` with the address of the new implementation and a future block number. The upgrade cannot execute until that block number is reached. When `upgradeToAndCall` is later invoked, the internal `_authorizeUpgrade` guard verifies the implementation matches the announcement and the delay has elapsed:


Suggested change

FWSS, PDPVerifier, and ServiceProviderRegistry each implement the same **two-step announce-then-upgrade** pattern. The owner first calls `announcePlannedUpgrade(PlannedUpgrade)` with the address of the new implementation and a future block number. The upgrade cannot execute until that block number is reached. When `upgradeToAndCall` is later invoked, the internal `_authorizeUpgrade` guard verifies the implementation matches the announcement and the delay has elapsed:

FWSS, PDPVerifier, and ServiceProviderRegistry each implement the same home-grown **two-step announce-then-upgrade** pattern. The owner first calls `announcePlannedUpgrade(PlannedUpgrade)` with the address of the new implementation (`PlannedUpgrade.nextImplementation`) and a future block number (`PlannedUpgrade.afterEpoch`). The upgrade cannot execute until that block number is reached. The minimum delay is at least 1 block. When [`upgradeToAndCall`](https://docs.openzeppelin.com/contracts/5.x/api/proxy#UUPSUpgradeable-upgradeToAndCall-address-bytes-) is later invoked, the internal `_authorizeUpgrade` guard verifies the implementation matches the announcement and the delay has elapsed:

I used "home grown" to make it clear that we aren't following an EIP here (but it is good/prudent to do). Maybe @wjmelements can point to industry best practice that we're modeling after.

SPEC.md

BigLep · 2026-02-25T23:36:01Z

SPEC.md

+
+See [`FilecoinWarmStorageService.sol:429-441`](https://github.com/FilOzone/filecoin-services/blob/main/service_contracts/src/FilecoinWarmStorageService.sol#L429-L441). The minimum code-length check (`code.length > 3000`) prevents accidental upgrades to empty or trivially small implementations. The `afterEpoch` delay gives users time to review the announced implementation before it takes effect.
+
+### Immutable Reference Coupling


Should we also talk about FWSS' reference to StateView. I see it stores one per https://github.com/FilOzone/filecoin-services/blob/main/service_contracts/src/FilecoinWarmStorageService.sol#L459-L496

SPEC.md

Co-authored-by: Steve Loeppky <biglep@filoz.org>

docs: document storage layout violations and backwards incompatibility

docs: move UUPS explenation into `Upgrade Mechanism` section

docs: change from ASCII to mermaid charts

rvagg · 2026-02-26T09:46:01Z

SPEC.md

+    Caller->>FilecoinPayV1: settleRail(railId)
+    FilecoinPayV1->>FWSS: validatePayment(railId, fromEpoch, toEpoch)
+    Note over FWSS: find proven periods in range
+    FWSS-->>FilecoinPayV1: provenEpochCount, finalSettlementEpoch


Not quite, see ValidationResult in FP. It doesn't care about proven epoch, it cares about modifiedAmount (<= the max settlement amount) and settleUpto (which epoch did we settle up to—in FWSS's case this'll usually come up to the end of the last proving period if you're trying to settle up to the current period)

SPEC.md

Co-authored-by: Rod Vagg <rod@vagg.org>

Document StateView's architecture, failure impact, and remediation in the contract architecture spec. Add FWSS's StateView storage variable reference to the Immutable Reference Coupling section. Fix settlement sequence diagram to return ValidationResult (modifiedAmount, settleUpto) instead of incorrect fields. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Fix data flow diagram callers and add schedule deletions

Add flow 6 (Next Proving Period) showing SP calling PDPVerifier.nextProvingPeriod, which triggers FWSS to process scheduled deletions and recalculate the payment rate. Clean up Schedule Deletions flow to only show the queuing step. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Reframe FilecoinPayV1 failure response by severity

docs: clarify StateView mutability and additive deploy behavior

docs: document contract architecture and failure scenarios

7cf3126

docs: document contract architecture and failure scenarios

rjan90 added this to the M4.1: mainnet ready milestone Feb 25, 2026

rjan90 self-assigned this Feb 25, 2026

rjan90 added this to FOC Feb 25, 2026

github-project-automation bot moved this to 📌 Triage in FOC Feb 25, 2026

rjan90 moved this from 📌 Triage to ⌨️ In Progress in FOC Feb 25, 2026

rjan90 added 2 commits February 25, 2026 11:49

fix: align edges of diagram correctly

dcbedff

fix: align edges of diagram correctly

chore: add links to USDFC token/contracts

bb31cc7

chore: add links to USDFC token/contracts

rjan90 marked this pull request as ready for review February 25, 2026 11:01

rjan90 requested review from BigLep and wjmelements February 25, 2026 11:02

rjan90 mentioned this pull request Feb 25, 2026

Document Contract Relationship and Migration Strategy #361

Open

BigLep moved this from ⌨️ In Progress to 🔎 Awaiting review in FOC Feb 25, 2026

BigLep reviewed Feb 26, 2026

View reviewed changes

BigLep moved this from 🔎 Awaiting review to ⌨️ In Progress in FOC Feb 26, 2026

rjan90 and others added 8 commits February 26, 2026 07:59

Update SPEC.md

4c20a19

Co-authored-by: Steve Loeppky <biglep@filoz.org>

Update SPEC.md

f53edf3

Co-authored-by: Steve Loeppky <biglep@filoz.org>

Update SPEC.md

b3445ee

Co-authored-by: Steve Loeppky <biglep@filoz.org>

Update SPEC.md

d237436

Co-authored-by: Steve Loeppky <biglep@filoz.org>

Update SPEC.md

09c3c63

Co-authored-by: Steve Loeppky <biglep@filoz.org>

docs: document storage layout violations and backwards incompatibility

2bc72be

docs: document storage layout violations and backwards incompatibility

docs: move UUPS explenation into Upgrade Mechanism section

8487886

docs: move UUPS explenation into `Upgrade Mechanism` section

docs: change from ASCII to mermaid charts

ce04f88

docs: change from ASCII to mermaid charts

rvagg reviewed Feb 26, 2026

View reviewed changes

SPEC.md Outdated Show resolved Hide resolved

rvagg reviewed Feb 26, 2026

View reviewed changes

SPEC.md Show resolved Hide resolved

rvagg reviewed Feb 26, 2026

View reviewed changes

SPEC.md Outdated Show resolved Hide resolved

rvagg reviewed Feb 26, 2026

View reviewed changes

SPEC.md Show resolved Hide resolved

rjan90 and others added 2 commits February 26, 2026 11:13

Update SPEC.md

459d888

Co-authored-by: Rod Vagg <rod@vagg.org>

rjan90 and others added 4 commits February 26, 2026 13:21

docs: fix data flow diagram callers and add schedule deletions

a80e15c

Fix data flow diagram callers and add schedule deletions

docs: reframe FilecoinPayV1 failure response by severity

b56e5ca

Reframe FilecoinPayV1 failure response by severity

docs: clarify StateView mutability and additive deploy behavior

bcb9676

docs: clarify StateView mutability and additive deploy behavior

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: document contract architecture and failure scenarios#430

docs: document contract architecture and failure scenarios#430
rjan90 wants to merge 17 commits intomainfrom
phi/contract-architecture-docs

rjan90 commented Feb 25, 2026 •

edited

Loading

Uh oh!

BigLep left a comment

Uh oh!

Uh oh!

Uh oh!

BigLep Feb 25, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

BigLep Feb 25, 2026

Uh oh!

Uh oh!

Uh oh!

rvagg Feb 26, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		### Upgrade Mechanism

		FWSS, PDPVerifier, and ServiceProviderRegistry each implement the same two-step announce-then-upgrade pattern. The owner first calls `announcePlannedUpgrade(PlannedUpgrade)` with the address of the new implementation and a future block number. The upgrade cannot execute until that block number is reached. When `upgradeToAndCall` is later invoked, the internal `_authorizeUpgrade` guard verifies the implementation matches the announcement and the delay has elapsed:


		See [`FilecoinWarmStorageService.sol:429-441`](https://github.com/FilOzone/filecoin-services/blob/main/service_contracts/src/FilecoinWarmStorageService.sol#L429-L441). The minimum code-length check (`code.length > 3000`) prevents accidental upgrades to empty or trivially small implementations. The `afterEpoch` delay gives users time to review the announced implementation before it takes effect.

		### Immutable Reference Coupling

Conversation

rjan90 commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

BigLep left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

BigLep Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

BigLep Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

rvagg Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

rjan90 commented Feb 25, 2026 •

edited

Loading