Hybrid Custody Mainnet Deployment Plan

🛠️ Builders 🏄🏻‍♀️ Cadence
1

HybridCustody Deployment Plan

Inspiration largely taken from Service Account procedures & infrastructure

Context

For most of 2023, the Flow community has been collaborating diligently to manifest a version of Hybrid Custody that works everyone. The vision of merging easy onboarding and seamless UX of app custody with the ownership and control provided by self-custody into a novel custodial pattern addressing the problems of both is about to make its way onto Mainnet.

The safety and security of this custodial pattern known as Hybrid Custody is entirely contingent upon contracts which enable this pattern. Given the number and variety of stakeholders involved, it’s important that we discuss and align on planned deployment, trusted custodial parties, and future update processes, the topics of which will be covered in this document.

Helpful Links

In case you haven’t been following along, below are some links you might find helpful:

Overview

Given the sensitivity and security concerns around Hybrid Custody, the community-led development of the final implementation, and the variety of stakeholders leveraging the functionality they introduce, it’s recommended that we take inspiration from existing core account infrastructure and the ecosystem precedents that have been set around such classes of contracts for the deployment of Hybrid Custody and its dependencies.

In the spirit of open source contribution and collaboration, this plan is presented as a point of conversation and to garner consensus around the final deployment plan for the Mainnet deployment of Hybrid Custody contracts (currently found at onflow/hybrid-custody). This also entails agreement upon governance structures and procedures that will preside over successive updates to deployed contracts.

Flow is committed to ensuring that the Hybrid Custody contract standard shall be a public good for the benefit of the community, which like other platform critical concerns, is managed using multi-sig. Key holders are established and trusted members of both the community and Flow whose role is to act in the best interest of the ecosystem in joint decisions.

Deployment & Update Plan

For simplicity and to remove multi-sig infrastructure as a dependency for Mainnet deployment, the proposed plan is to deploy contracts with a single signer managed by Flow. This post here is to help us align on agreements & expectations around ongoing update governance and management.

Once successful deployment is confirmed, we’ll add the public keys of each agreed upon key holder (at a weight of 250) and, within the subsequent days, configure a repo as a point of communication & coordination for future updates to the contract with key holders added to the repo as maintainers.

Future Update Process

As-is, contract updates will be needed for the Stable Cadence milestone. Executing these updates will be a sensitive matter, and should reflect the processes adopted for the service account contracts to ensure security, transparency, and redundancy, at least as long as keys are active on the deployment account.

Using the yet to be created onflow/hybrid-custody-account repo (similar to onflow/service-account), proposed transactions will be submitted for review via PR. Upon merging, maintainers will communicate a date and time for signers to sign the approved and merged transactions and follow through as agreed.

Beyond Stable Cadence

In an ideal world, no one would have access to the underlying contract account. While we’re not yet at the place we can deploy & forget, the Stable Cadence milestone may mark a time when we can safely revoke keys on this account. This is at least worth mentioning as we move toward increasing decentralization and trustlessness on Flow. After 3-4 months post-Stable Cadence, key holders should convene to discuss the possibility for if/when they deem it fitting to revoke their key access on the deployment account.

Proposed Key Holders

As previously stated, the Hybrid Custody initiative has been a nearly year-long process of ideation, prototyping, iterating, and refining, with critical input, consultation, design, and collaboration with a number of core community contributors.

Given the number of contributors and variety of stakeholders, it’s recommended that the final key holders similarly represent the variety of perspectives and their users and interests while also taking into account the builders and voices involved in making Hybrid Custody a reality.

As such, the proposed list of key holders for community consideration are as listed below. This being a proposal, this list isn’t final - no one below is obligated to take on key holder responsibility and other individuals/entities can be raised for consideration:

Implementation Notes

To follow once party consensus and agreement has been confirmed. Note that infrastructure will largely follow patterns utilized by the service account unless there is key holder consensus otherwise.

Hosted Factories

Context

Applications implementing Hybrid Custody can (and are recommended to) set restrictions on the scope of access a parent account can have on a child account. These rule sets and access patterns are defined in CapabilityFilter and CapabilityFactory objects respectively. Proper configuration of these constructs is important because a developer could easily expose themselves to undue risk if they use the wrong Factory or implement their own incorrectly.

Because of this, and due to the sensitive nature around the Factory Capability retrieval method signature, it’s recommended that developers avoid rolling their own implementations and stick to those in the source repo.

However, configuring a CapabilityFactory implementation is still a necessary step for developers implementing Hybrid Custody in their applications, and could be a significant friction point if developers are not well supported.

Proposal

@austin proposed common-use Factory implementations be community-hosted and recommended for use in the process of linking parent & child accounts. This would support developers by removing a step in their setup process and avoids potential footguns where a developer implements and uses a poorly constructed factory for their use case.

However, adoption of these hosted factories also introduces a centralized point of failure. The concern here is that the hosting account is compromised and contract updated such that a large fraction of hybrid custody accounts are compromised via the Capability retrieval path.

A mitigation step here might be to revoke all keys on the hosting account to prevent the vulnerability altogether. Another might be to configure the accounts under the same multi-sig custodial pattern as utilized by the Hybrid Custody contract account. This way all HC-related updates and changes are routed through equivalent governance and approval processes.

Next Steps

In the conversation this post kicks off, we’ll want to align on the following:

  • Are we in agreement on the proposed key holders?

  • Do the proposed key holders agree to take on the responsibility?

    • If not, how do we feel about the resulting balance? Are any resulting changes necessary to achieve consensus?

  • Do we agree on configuring hosted factories?

    • What mitigation steps if any would we like to adopt for the hosting accounts?

Beyond that, we’ll want to push forward the FLIP in the approval process (update to follow in the next day), deploy the contracts, configure the deployment account with agreed upon signers & setup the onflow/hybrid-custody-account repo.

The hope here is we can align and close up any of the logistical & operations work above to deploy by Wednesday, August 9th.

References

2 Likes
2

Thanks for the write-up @gio_on_flow!

One callout for discussion, and one suggestion as it pertains to the signers themselves

Discussion point:
Based on the current list, Flow would have enough multi-sigs to be able to deploy on their own with no external party consenting. Is this intentional? If 4 is the number flow wants, I would say that each key’s weight should be 200, not 250. No single organization should have enough signing weight to be able to make decisions on their own

Suggestion:
I’m sure all of the people from Flow on your list are well-suited to be on the multi-sig. I do notice, however, that @Hao is not on that list. My understanding is that Hao works on the Flow team, and are a great representative for wallet stakeholders which I think warrants consideration.

Probably to most of us outside of the Flow team, who from Flow is in the multi-sig isn’t as important as how many there are and what weight that amounts to

3

For the CapabilityFactory pre-made resources, and for CapabilityFilter resources that make sense to be shared (like an allow-all filter), I think that the same multi-sig is probably the most consistent way to go. Perhaps the main annoyance with this approach is that it means the multi-sig has to be managed in multiple places.

Perhaps we can use our own implementation with HybridCustody to make accounts owned by the multi-sig so that access moves with the multi-sig itself?

4

I think we can trim this list a bit ( by weights or signers ) I think Flow/Dapper 3 signers ( 1 dapper + 1 flow + 1 hao ) and 5 outside ( with 200 weight each, requiring 5 / 8 is ideal )

2 Likes
5

+1 I’m in favor of this ^

Maybe the list looks like:

Community:

Dapper:

Flow:

Realistically, it’s more about the organizations being represented. Dapper, Flow, or any other org here could send anyone they want as a rep

2 Likes
6

This list looks good to me, and I think 5/8 is a fair distribution. Agreed that @Hao should be added as a signer.

The idea of using HC to manage the hosting accounts is interesting :thinking: I’m open to that idea - I guess we’d set the HC deployment account as owner of all host accounts?

Entertaining alternatives here, could we just add the same keys on to the Factory host accounts?

7

Can we use the FLIP process for any updates to the hybrid-custody contracts?
The actual update of the contract can still be executed by the key holders, but arriving at a consensus on the change itself can be done via the FLIP process which the community is already familiar with.

8

We definitely can take either approach, here. The reason I was suggesting letting the multi-sig account utilize child accounts to manage the rest is mostly so that updating signers would only have to be done in one place. That likely isn’t a strong enough reason to make things more complicated than is needed and we can always move to another pattern that makes more sense if we need to

9

My expectation for updates is that we will need to follow the same process as is used for FungibleToken, NonFungibleToken, or any other sensitive contract that is treated as a primitive in any way. Do they use the FLIP process? I’m not very familiar with how updates reach them generally

10

@flowjosh has been working on NFTv2 updates and I believe that’s coordinated through the FLIP process.

On that note, the HC FLIP has been updated and could use some feedback as well!

11

For the token standards, if there is a large significant update to the functionality, then we’ll go through a FLIP, but if it is just a small change like adding the getSupportedVaultTypes to FungibleToken.Receiver or adding borrowNFTSafe to the NFT standard, then we have just been doing that through issues in the repo. The v2 standards are FLIPs for those reasons.

12

Circling back to call for any last minute feedback over the weekend. Contracts have been deployed! Pease leave any final signal here about ongoing deployment account management and on the FLIP if you have any!