Decision: Endorsement Certificates vs Smart Contract Approach

[rvagg]

Background

We have a three-tier provider trust model:

1. All providers (outer circle): Everyone registered in ServiceProviderRegistry
2. Approved providers (middle circle): Providers that meet baseline requirements, recorded in FilecoinWarmStorageService
3. Endorsed providers (inner circle): Small set of providers highly trusted by us that we will (initially) be storing at least one copy of everything on

This decision concerns how we identify the endorsed tier.

The core issue

The current proposed mechanism, "endorsement certificates" are using complex cryptographic machinery (EIP-712 signed certificates, distributed via SP capability metadata) to solve what is fundamentally a simple trust problem: "Which SPs should I store at least one copy with?"

For a small, curated inner circle, this complexity may not be justified, particularly since we don't believe this problem will exist as we proceed with future plans for the MSP intermediary layer.

Concerns with endorsement certificates

Complexity:

• Significant implementation effort, still incomplete after multiple review rounds (but not too hard to finish)
• SP selection logic is becoming difficult to explain
• More moving parts = more failure modes

Operational burden:

• Requires SP participation: they must submit certificates to their registry entry
• Adds delay and coordination overhead
• Requires confirmation by us after SP submission

Security:

• No multisig: any one of three wallets (Tippy, Orjan, Jenny) can endorse
• Single wallet compromise affects entire endorsement chain
• No revocation mechanism--only certificate timeout
• Cannot react quickly to trust changes or SP quality issues

Performance:

• Must walk entire registry to find endorsed providers
• Adds latency at startup before system functions

Proposed alternative: endorsed providers contract

A standalone contract holding a list of endorsed provider IDs:

• Owner (multisig) can add/remove providers on demand
• SDK fetches list in parallel with other initialization
• Immediate revocation capability
• O(1) lookup vs O(n) registry walk
• Appropriate complexity for managing a small curated list

Effort estimate: ~2-3 days

• Author contract + basic tests
• Add to deployment scripts and docs
• Hardcode address per-network in SDK (we could add another address record to FWSS, but I think we can treat this as a separate concern to core FWSS)
• Add query to SDK

Decision framework

Ignoring sunk cost:

Aspect	Certificates	Simple Contract
Immediate cost	Lower (PR nearly ready)	Moderate (new work)
Ongoing complexity	High	Low
Security model	Weaker (single-sig)	Stronger (multisig)
Revocation	None (timeout only)	Immediate
SP coordination	Required	None
Explainability	Difficult	Trivial
Fit for small list	Over-engineered	Appropriate

Lock-in

Whichever approach ships, we must support it for the lifetime of SDK versions containing it. Switching later means maintaining both mechanisms in parallel for some period of time and we won't know for sure how long it would be.

With endorsement certificates and their expiry, we'd have the possibility of older SDK users looking for endorsed SPs and finding none once we stop updating them.

Options

1. Proceed with endorsement certificates: PR feat: Endorsement Certificates #443 is close to ready, but needs certificates rolled out to SPs and testing. Lowest immediate cost, but carries ongoing burdens.
2. Implement simple contract: Moderate upfront cost, but operationally simpler and more secure long-term.

[wjmelements]

I disagree with most of these points in your analysis.

[wjmelements]

complex cryptographic machinery (EIP-712 signed certificates

EIP-712 is the standard way to sign typed data. It is supported by most cryptocurrency wallets. It is not complicated.

Significant implementation effort
Over-engineered

Quantitatively, the PR is (+540, -43). About half of that is tests. The work specific to endorsement certificates was a fraction of that. We chose this approach because it was simplest. More time has been spent bikeshedding than will be saved operationally.

still incomplete after multiple review rounds (but not too hard to finish)

The code is complete and should have merged long ago.

SP selection logic is becoming difficult to explain

This is not a problem specific to endorsement certificates. It is a problem with having additional tiers. I don't like it either and it wasn't the solution I recommended.

More moving parts = more failure modes

What do you mean by this?

Must walk entire registry to find endorsed providers

I am not sure what you mean by this. I suspect it is a misunderstanding.

We walk over all of the values because we haven't specified a key, but the number of attributes is a bounded constant, and we are already walking over all of them when we decode SP metadata.

It does not trigger additional RPC requests because the information is already loaded. The method is async because viem's public key recovery method is async, and that is only because they lazy-load that module. Very annoying.

Adds latency at startup before system functions

I doubt this. Have you measured it? The new smart contract would add additional RPC queries not required by endorsement certificates.

Operational burden

This is valid, though you spread it out into three bullet points. Another concern you don't bring up here is that when they expire they will need to be renewed.

No multisig
Single wallet compromise affects entire endorsement chain

It's a 1 of 3 multisig currently but the threshold is configurable. A bigger problem is that the signers are encoded in the SDK.

(Tippy, Orjan, Jenny) can endorse

It is very bad for SPs to have endorsement authority because they can sybil.

No revocation mechanism

The revocation plan is to remove them from the approved provider tier. This is compatible with our threat model for endorsed SPs.

Cannot react quickly to trust changes or SP quality issues

This is true. However, our threat model is that no endorsed SPs have serious issues until we can migrate to MSP. If we think that is a real possibility then we should not have this tier at all.

With endorsement certificates and their expiry, we'd have the possibility of older SDK users looking for endorsed SPs and finding none once we stop updating them.

The SDK handles this by falling back to the approved providers and I think that's fine. Although you observe this concern is not unique to endorsement certificates you bold the problem with endorsement certificates and omit the corresponding problem with a smart contract, equivalent to certificates with no expiry. I think expiry handles this situation better, but not by much.

Summary

Aspect	Endorsement Certificates in SP Registry	Endorsement Registry
Readiness	done	additional week
Signers	baked into SDK	mutable on-chain
Revocation	via SP approval	via Endorsement Registry
SP coordination	required	none

I agree that using an endorsement registry is superior operationally. The main benefit is that we don't need to have SPs enter certificates, which will borrow some time in the Curio work (until the next time we want to encode bytes).

We preferred typed data reusing our existing SP Registry because it was very simple for a temporary solution with trust assumptions, but it seems we are now doubting both of those parameters, so I would be happy to work on an endorsement registry.

[rvagg]

re "vs Simpler Approach" in the title, one thing omitted from the ongoing discussion that's lead to this issue is other alternatives, such as just baking in provider IDs into the SDK itself. Those are on the table, but I didn't bother writing that one up. For completeness though: baking IDs into the SDK suffers from the obvious problem of having no good path to revocation or modification since we don't have a good forcing function to have devs upgrade SDK versions. Perhaps if we had such a method we could achieve that but it's pretty hostile to do things like phone-home+nag, or even hard-deprecate versions in the registry, so it's far less than ideal. Other ideas are welcome though.

[timfong888]

My take and considerations currently:

1. SP Coordination Burden: given the other considerations we have getting quality of service and potentially other upgrades, I weigh a no SP coordination higher.

2. Long-term Support Burden: right now, things that "break" without upgrading versus living with friction is more of a concern for me; this being said, I would like to know what our versioning/backward compatability is, but as a general principle, with what I know, this also makes me concerned by Endorsement Registry based on my understanding.

These lead me to the contract vs endorsement certs.

[BigLep]

It was useful to get more information about endorsement certificates and to understand that some areas of concern aren't as concerning or have mitigation.

I agree that if an endorsed SP is having "problems" and we need to quickly remove them from being "endorsed" that dropping them from the SP approval list is an acceptable response.

That's great to know there aren't startup performance concerns about the "endorsement certificate" approach.

It's good to know that we can avoid the "single wallet compromise affects entire endorsement chain" by requiring endorsement from two signers that are encoded into Synapse (i.e., "multisig in spirit"). That said If we want to support N signers, I believe that means N people will need to run endorse-sp.js and then the SP now needs to include N of them? Oof - so even more coordination. That's bad.

• That said, looking at this from the worst case if we only require 1... If an endorser gets compromised, my understanding is that the attacker can then self-service endorse any SP. But does the SP still needs to be in the loop to add the endorsement into the SP registry. If that's the case, that doesn't seem so bad. Yes that means an attacker could endorse an SP that they have control of, but that is more challenging coordinated attack. As a result, if we go with endorsement certificates, I'm ok with the risk of N=1.

My biggest remaining concern about "endorsement certificates" is around operations as well (e.g., needing to involve and coordinate with SPs, and that we need to do this each time to renew).

If we stay on the "endorsement certificate" approach, we still have a bit more work:

1. Adjust code to require endorsement from two signers (not just one) (I assume this is easy, but I would skipt it because I don't think the risk/benefit is worth it.)
2. Runbook for how SPs generate and submit certificates to their registry entry.
3. Runbook for how FOC maintainers endorse these certificates.
   I know this isn't a lot of work. I'm just making clear that endorsement certificates isn't fully done yet.

And I know too that if we switch to endorsed providers contract we have more work (develop/deploy new contract, Synapse work to query the contract, runbook for how to add an endorsed SP).

With what I know now, I would vote to switch to the "endorsed providers contract" because of the operational reasons. That said, I don't feel as strongly about this as I did before learning more today. So I am happy to support sticking with "endorsement certificates" as well.

It seems like the general consensus at this point is to use "endorsed providers contract" so unless there is new information or objection, lets go that path. I think the plan would be for @wjmelements to do this work the week of 2026-01-12 when he's back.

[rvagg]

Created task: FilOzone/filecoin-services#382