[DOCS] Hybrid Custody

[sideninja]

I think we should divide the concepts of hybrid custody and account linking. One is a design approach of Flow dapps and the other is a Cadence feature. Putting both together in docs creates unnecessary added complexity.

Suggested actions:

Update Dapp Architectures
Update the Dapp Architectures on the Flow Blockchain with the hybrid custody and explain how you can achieve that through account linking which would link back to the account linking docs.

Refresh the diagrams in the article with a bit more modern-looking ones, and take the user through an example of the process:

• User signups to a rock paper scissors game in a web2 conventional ways (via email, phone number etc)
• The user plays the game without any need to create a Flow wallet, they can pay for playing by providing a credit card
• User matures and becomes web3 native, it creates it's own Flow wallet and now wants to access to assets created inside the game, they can do so by using the account linking feature of Flow

Link the hybrid custody page to the above doc https://flow.com/hybrid-custody

Hybrid Custody -> Account Linking
Hybrid custody is a new term that doesn't include any idea of what it means. Account linking as a term is more self-explanatory and conveys the idea faster. More than that, account linking is more powerful than just hybrid-custody, hybrid-custody is merely an example of application of account linking. It also adds to complexity of trying to explain two concepts at the same time.

• Change the Hybrid custody to account linking and present it as a Cadence feature. Remove the added content about Hybrid Custody as is explained in the above guide, which is mentioned as an application of this feature and then linked to that guide.
• Move account abstraction into another section (TBD), it doesn't help explain what account linking is
• Make Linking Accounts into Cadence Linking Accounts
  • This section needs to reference the capability document as a prerequisite for understanding the content
• Add a Linking Accounts page that explains in simple terms what it is. Include graphic diagrams to explain the idea behind it. Also surface the intro content from current account linking document and keep that document more technical with examples.
• Create a scaffold that only contains the simplest example how you can link an account, the example could be:
  • Add a scaffold with a simple account linking example, create a account A funded with Flow, create another account B, link account A as a child to B, and transfer Flow from account B.
• Remove Walletless Onboarding, it adds another term that needs explaining, it doesn't explain account linking, it doesn't introduce anything new

FLIX

• Add support for account linking templates so we can include them as part of the example

Implications on other parts:

• Should we rename hybrid custody contracts to account linking, as it even says in the comment it says account linking
• Implementing a wrapper of HC to contain default values for filters and can be easier to use for learning purpose.

[sisyphusSmiling]

I agree with the suggestions here. HC on its own is a lot to digest without understanding the concept of account linking (i.e. Account Capabilities).

I would add here that maybe instead of a scaffold we create a simple Cadence tutorial where a dev walks through:

1. Creating AuthAccount Capability
2. Publishing that Capability for someone via AuthAccount.Inbox
3. Claiming that Capability
4. Using that Capability to access something in the publishing account

This also brings up the need for an inbox tutorial, but that's spinning out of scope.

[sideninja]

Can we instead of using inbox make a multi-sig transaction to simplify? but I agree, maybe we can split it into two, first is just native account linking and then we have HC for more advance usage as a continuing on the idea. That way users will be able to have a step in between.

[sideninja]

@btspoony Came to a similar conclusion about developing a wrapper for learning purposes. As he explained on Discord: https://discord.com/channels/613813861610684416/1087374662100602920/threads/1136892613270704159

HybridCustodyHelper

• He has the ManagerAccount as AuthAccount and created the UserAccount in the transaction.
• Call HybridCustodyHelper.assignNewChild(managerAcct, childAcctCap), that's it.
• He doesn't need to fuss about anything and completed the first step very intuitively: set UserAccount as a child of ManagerAccount

[sideninja]

I believe a good approach from tutorial perspective could be:

1. We introduce basic account linking, we explain the feature, make sure devs are aware of capabilites (linked to that), then we graphically present the concept, and we make a simple example, as the one @sisyphusSmiling mentioned, at that point we can expect from the developer to understand the basic concept how can two accounts be connected and if we are naive we can say he knows enough
2. We explain why using account linking as it is directly is not safe for production usage, we explain that we need more code to make it secure and production ready, we introduce a wrapper to HC that presents a simple example similar to what @btspoony said,
3. Finally we explain to the user with current docs on HC what is the final step (current docs on account linking is great).

[btspoony]

For reference, the HybridCustodyHelper’s code

https://github.com/btspoony/hybrid-custody-helper/blob/main/contracts/HybridCustodyHelper.cdc

[sisyphusSmiling]

Can we instead of using inbox make a multi-sig transaction to simplify? but I agree, maybe we can split it into two, first is just native account linking and then we have HC for more advance usage as a continuing on the idea. That way users will be able to have a step in between.

Sure, multisig would definitely work for demonstration. Feedback we've gotten from builders working with custodial services points to multi-sig being a pain to implement. Based on that feedback, I've been inclined to demo publish/claim so the pattern devs encounter are consistent across the full stack. Do you know if there's an easy way to setup a multi-sig txn or are devs more inclined to deal with single-signed txns?

We explain why using account linking as it is directly is not safe for production usage, we explain that we need more code to make it secure and production ready, we introduce a wrapper to HC that presents a simple example similar to what @btspoony said

I think this is alright for the purposes of learning, but I still wouldn't recommend devs rely on a wrapper as a crutch in production. If they build their entire interface around the wrapper, they'll run into issues when most accounts they encounter don't have wrappers configured.

I think the overall order of concepts does a better job of ramping devs up to the fully-fledged HC construction. With that said, most devs dealing with HC really won't need to concern themselves with the deeper concepts, so ramping them up to hold the entire construction in mind feels unnecessary.

@sideninja from our convo this week, we mentioned focussing on the app dev person. The only devs who will need to deeply understand and use HC constructs are platforms & wallets, of which there are few. I think we'll get the most impact by simplifying the app path which involves the following steps:

One-time setup:

1. Select a hosted CapabilityFactory Manager implementation or configure one yourself
2. Configure a CapabilityFilter implementation and add your allowed/denied types

When it's time to link:

1. Complete the publishToParent() transaction signing as the publishing child account and providing Display view info for the account's app association
2. Have the parent sign a claiming transaction, optionally configuring any app-related resources in the parent account (e.g. an NFT Collection)

And that's pretty much the extent most apps will have to go to allow parent wallets to link app-custodied child accounts.

Getting child account Capabilities, resolving child account metadata, facilitating cross-account transactions - all of that complexity will be dealt with by wallets and platforms. I feel like optimizing for these builders first means we're ignoring the low-hanging fruit we gain by making it easy for devs to enable linking parent-child accounts.

[sideninja]

Based on that feedback, I've been inclined to demo publish/claim so the pattern devs encounter are consistent across the full stack.

I agree then!

Do you know if there's an easy way to setup a multi-sig txn

Using CLI you can, but again, if there's feedback around it then we should do it that way.

I think we'll get the most impact by simplifying the app path which involves the following steps

I agree. This could be a nice example as a step towards existing material around HC.
Maybe this is a good candidate for a scaffold that demonstrates just these actions. We could add a simple UI as well.

[sisyphusSmiling]

SGTM, I like the idea of a minimized scaffold that works as an experiential demo w/ UI

[nvdtf]

The Hybrid Custody section was updated to Account Linking: https://developers.flow.com/next/concepts/account-linking
I did some quick updates with respect to this issue as well but it's not completely covered, so keeping this still open in case we need to update the contents (I only remixed).