Account Model & Implementation

This doc serves as developer guidance to support Hybrid Custody apps by leveraging Account Linking. While account linking as a feature is a language level API, supporting linked accounts such that users achieve Hybrid Custody has a bit more nuance, namely that apps should build on the HybridCustody standard proposed in FLIP #72. Implementing this standard will allow dapps to facilitate a user experience based not on a single authenticated account, but on the global context of all accounts linked to the authenticated parent account.

We believe multi-account linking and management, technical initiatives in support of Walletless Onboarding, will enable in-dapp experiences far superior to the current Web3 status quo and allow for industry UX to finally reach parity with traditional Web2 authentication and onboarding flows, most notably on mobile.

A new user will no longer need a preconfigured wallet to interact with Flow. When they do decide to create a wallet and link with a dapp; however, the associated accounts and assets within them will need to be accessible the same as if they were in a single account.

In order to realize a multi-account world that makes sense to users - one where they don't have to concern themselves with managing assets across their network of accounts - we're relying on Flow builders to cast their abstractive magic. These docs will provide you with components and steps to create those abstractions for your users. In this doc, we'll continue from the perspective of a wallet or marketplace dapp seeking to facilitate a unified account experience, abstracting away the partitioned access between accounts into a single dashboard for user interactions on all their owned assets.

danger

Note that the documentation on Hybrid Custody covers the current state and will likely differ from the final implementation. Builders should be aware that breaking changes may follow before reaching a final consensus on implementation. Interested in shaping the conversation? Join in!

Objectives

Understand the Hybrid Custody account model
Create a blockchain-native onboarding flow
Link an existing app account as a child to a newly authenticated parent account
Get your dapp to recognize “parent” accounts along with any associated “child” accounts
View Fungible and NonFungible Token metadata relating to assets across all of a user's associated accounts - their wallet-mediated “parent” account and any hybrid custody model “child” accounts
Facilitate transactions acting on assets in child accounts

Design Overview

info

TL;DR: An account's HybridCustody.Manager is the entry point for all of a user's associated accounts.

The basic idea in the (currently proposed) standard is relatively simple. A parent account is one that has received delegated (albeit restricted) access on another account. The account which has delegated authority over itself to the parent account is the child account.

In the Hybrid Custody Model, this child account would have shared access between the dapp - the entity which created likely custodies the account - and the linked parent account.

How does this delegation occur? Typically when we think of shared account access in crypto, we think keys. However, Cadence enables accounts to link Capabilities to themselves and issue those Capabilities to other parties (more on capability-based access here).

We've leveraged this feature in a (proposed) standard so that dapps can implement a hybrid custody model whereby the dapp creates an account it controls, then later delegates access on that account to the user once they've authenticated with their wallet.

All related constructs are used together in the HybridCustody contract to define the standard.

Parent accounts own a Manager resource which stores Capabilities to ProxyAccount (restricted access) and ChildAccount (unrestricted access) resources, both of which are stored in any given child account.

Therefore, the presence of a Manager in an account implies there are potentially associated accounts for which the owning account has delegated access. This resource is intended to be configured with a public Capability that enables querying of an account's child account addresses via getAccountAddresses() and getOwnedAccountAddresses().As you can deduce from these two methods, there is a notion of "owned" accounts which we'll expand on in a bit.

A wallet or marketplace wishing to discover all of a user's accounts and assets within them can do so by first looking to the user's Manager.

Identifying Account Hierarchy

To clarify, insofar as the standard is concerned, an account is a parent account if it contains a Manager resource, and an account is a child account if it contains at minimum a ChildAccount or additionally a ProxyAccount resource.

We can see that the user's Manager.accounts points to the addresses of its child accounts in each index, with corresponding Capabilities giving the Manager access to those accounts.

Likewise, the child account's ProxyAccount.parentAddress (which owns a Manager) points to the user's account as its parent address. This makes it easy to both identify whether an account is a parent, child, or both, and its associated parent/child account(s). ChildAccount resources underly all account delegations, so can have multiple parents whereas ProxyAccounts are 1:1. This provides more granular revocation as each parent account has its own Capability path on which its access relies.

Restricted vs. Owned Accounts

It's worth noting here that ProxyAccount Capabilities enable access to the underlying account according to rules configured by the child account who is delegating the authority. The ProxyAccount maintains these rules along with a ChildAccount Capability within which the AuthAccount Capability is stored. Anyone with access to the surface level ProxyAccount can then access the underlying AuthAccount, but only according the pre-defined rule set. These rules are fundamentally a list of Types that can/cannot be retrieved from an account.

HybridCustody Conceptual Overview

The app developer can codify these rule sets on allowable Capability types in a CapabilityFilter along with a CapabilityFactory defining retrieval patterns for those Capabilities. When delegation occurs, the developer would provide the CapabilityFilter and CapabilityFactory Capabilities to a ChildAccount resource which stores them in a ProxyAccount resource. Then, capabilities are created for the ChildAccount and ProxyAccount resource and are given to the specified parent account.

So, if an app developer wants to enable Hybrid Custody but doesn't want to allow parent accounts to access FungibleToken Vaults, for example, the app developer can codify rule sets enumerating allowable Capability types in a CapabilityFilter along with a CapabilityFactory defining retrieval patterns for those Capabilities. When delegation occurs, they would provide the CapabilityFilter and CapabilityFactory Capabilities to a ChildAccount. This ChildAccount then wraps the given filter & factory Capabilities in a ProxyAccount along with a Capability to itself before publishing the new ProxyAccount Capability for the specified parent account to claim.

info

Note that by enumerating allowable Types in your CapabilityFilter.Filter implementation, you're by default excluding access to anything other than the Types you declare as allowable.

As mentioned earlier, Managers also maintain access to "owned" accounts - accounts which define unrestricted access as they allow direct retrieval of encapsulated AuthAccount objects. These owned accounts, found in Manager.ownedAccounts, are simply ChildAccount Capabilities instead of ProxyAccount Capabilities.

HybridCustody Total Overview

Considerations

Do note that this construction does not prevent an account from having multiple parent accounts or a child account from being the parent to other accounts. While initial intuition might lead one to believe that account associations are a tree with the user at the root, the graph of associated accounts among child accounts may lead to cycles of association.

We believe it would be unlikely for a use case to demand a user delegates authority over their main account (in fact we'd discourage such constructions), but delegating access between child accounts could be useful. As an example, consider a set of local game clients across mobile and web platforms, each with self-custodied app accounts having delegated authority to each other while both are child accounts of the user's main account.

Ultimately, it will be up to the implementing wallet/marketplace how far down the graph of account associations they'd want to traverse and display to the user.

Implementation

From the perspective of a wallet or marketplace dapp, some relevant things to know about the user are:

Does this account have associated linked (child) accounts?
What are those associated linked accounts, if any?
What NFTs are owned by this user across all associated accounts?
What are the balances of all FungibleTokens across all associated accounts?

And with respect to acting on the assets of child accounts and managing child accounts themselves:

Accessing an NFT from a linked account's Collection
Removing a linked account

Examples

Query Whether an Address Has Associated Accounts

This script will return true if a HybridCustody.Manager is stored and false otherwise

get_child_addresses.cdc

import "HybridCustody"
pub fun main(parent: Address): Bool {
    let acct = getAuthAccount(parent)
    if let manager = acct.borrow<&HybridCustody.Manager>(from: HybridCustody.ManagerStoragePath) {
        return manager.getAddresses().length > 0
    }
    return false
}

Query All Accounts Associated with Address

The following script will return an array addresses associated with a given account's address, inclusive of the provided address.

get_child_addresses.cdc

import "HybridCustody"
pub fun main(parent: Address): [Address] {
    let acct = getAuthAccount(parent)
    let manager = acct.borrow<&HybridCustody.Manager>(from: HybridCustody.ManagerStoragePath)
        ?? panic("manager not found")
    return manager.getAddresses() // Could also call getOwnedAddresses() for owned account addresses
}

Query All Owned NFT Metadata

While it is possible to iterate over the storage of all associated accounts in a single script, memory limits prevent this approach from scaling well. Since some accounts hold thousands of NFTs, we recommend breaking up iteration, utilizing several queries to iterate over accounts and the storage of each account. Batching queries on individual accounts may even be required based on the number of NFTs held.

Get all associated account addresses (see above)
Looping over each associated account address client-side, get each address's owned NFT metadata

get_nft_display_view_from_public.cdc

import "NonFungibleToken"
import "MetadataViews"
import "HybridCustody"
/// Returns resolved Display from given address at specified path for each ID or nil if ResolverCollection is not found
///
pub fun getViews(_ address: Address, _ resolverCollectionPath: PublicPath): {UInt64: MetadataViews.Display} {
    let account: PublicAccount = getAccount(address)
    let views: {UInt64: MetadataViews.Display} = {}
    // Borrow the Collection
    if let collection = account
        .getCapability<&{NonFungibleToken.CollectionPublic, MetadataViews.ResolverCollection}>(resolverCollectionPath).borrow() {
        // Iterate over IDs & resolve the view
        for id in collection.getIDs() {
            let display = collection.borrowViewResolver(id: id).resolveView(Type<MetadataViews.Display>()) as! MetadataViews.Display
            views.insert(key: id, display)
        }
    }
    return views
}
/// Queries MetadataViews.Display for each NFT across all associated accounts from Collections at the provided
/// PublicPath
///
pub fun main(address: Address, resolverCollectionPath: PublicPath): {Address: {UInt64: MetadataViews.Display}} {
    let allViews: {Address: {UInt64: MetadataViews.Display}} = {address: getViews(address, resolverCollectionPath)}
    let seen: [Address] = [address]
    /* Iterate over any associated accounts */ 
    //
    if let managerRef = getAuthAccount(address).borrow<&HybridCustody.Manager>(from: HybridCustody.ManagerStoragePath) {
        for childAccount in managerRef.getChildAddresses() {
            allViews.insert(key: childAccount, getViews(address, resolverCollectionPath))
            seen.append(childAccount)
        }
        for ownedAccount in managerRef.getOwnedAddresses() {
            if seen.contains(ownedAccount) == false {
                allViews.insert(key: ownedAccount, getViews(address, resolverCollectionPath))
                seen.append(ownedAccount)
            }
        }
    }
    return allViews 
}

After iterating over all associated accounts, the client will have a mapping of Display views indexed on the NFT ID and grouped by account Address. Note that this script does not take batching into consideration and assumes that each NFT resolves the MetadataViews.Display view type.

Query All Account FungibleToken Balances

Similar to the previous example, we recommend breaking up this task due to memory limits.

Get all linked account addresses (see above)
Looping over each associated account address client-side, get each address's owned FungibleToken Vault metadata

However, we'll condense both of these steps down into one script for simplicity:

get_all_vault_bal_from_storage.cdc

import "FungibleToken"
import "MetadataViews"
import "HybridCustody"
/// Returns a mapping of balances indexed on the Type of resource containing the balance
///
pub fun getAllBalancesInStorage(_ address: Address): {Type: UFix64} {
    // Get the account
    let account: AuthAccount = getAuthAccount(address)
    // Init for return value
    let balances: {Type: UFix64} = {}
    // Track seen Types in array
    let seen: [Type] = []
    // Assign the type we'll need
    let balanceType: Type = Type<@{FungibleToken.Balance}>()
    // Iterate over all stored items & get the path if the type is what we're looking for
    account.forEachStored(fun (path: StoragePath, type: Type): Bool {
        if type.isInstance(balanceType) || type.isSubtype(of: balanceType) {
            // Get a reference to the resource & its balance
            let vaultRef = account.borrow<&{FungibleToken.Balance}>(from: path)!
            // Insert a new values if it's the first time we've seen the type
            if !seen.contains(type) {
                balances.insert(key: type, vaultRef.balance)
            } else {
                // Otherwise just update the balance of the vault (unlikely we'll see the same type twice in
                // the same account, but we want to cover the case)
                balances[type] = balances[type]! + vaultRef.balance
            }
        }
        return true
    })
    return balances
}
/// Queries for FT.Vault balance of all FT.Vaults in the specified account and all of its associated accounts
///
pub fun main(address: Address): {Address: {Type: UFix64}} {
    // Get the balance for the given address
    let balances: {Address: {Type: UFix64}} = { address: getAllBalancesInStorage(address) }
    // Tracking Addresses we've come across to prevent overwriting balances (more efficient than checking dict entries (?))
    let seen: [Address] = [address]
    
    /* Iterate over any associated accounts */ 
    //
    if let managerRef = getAuthAccount(address)
        .borrow<&HybridCustody.Manager>(from: HybridCustody.ManagerStoragePath) {
        
        for childAccount in managerRef.getChildAddresses() {
            balances.insert(key: childAccount, getAllBalancesInStorage(address))
            seen.append(childAccount)
        }
        for ownedAccount in managerRef.getOwnedAddresses() {
            if seen.contains(ownedAccount) == false {
                balances.insert(key: ownedAccount, getAllBalancesInStorage(address))
                seen.append(ownedAccount)
            }
        }
    }
    return balances 
}

The above script returns a dictionary of balances indexed on the type and further grouped by account Address.

The returned data at the end of address iteration should be sufficient to achieve a unified balance of all Vaults of similar types across all of a user's associated account as well as a more granular per account view.

You might consider resolving FungibleTokenMetadataViews to aggregate more information about the underlying Vaults.

Access NFT in Child Account from Parent Account

A user with tokens in one of their linked accounts will likely want to utilize said tokens. In this example, the user will sign a transaction a transaction with their authenticated account that retrieves a reference to a linked account's NonFungibleToken.Provider, enabling withdrawal from the linked account having signed with the main account.

withdraw_nft_from_child.cdc

import "NonFungibleToken"
import "FlowToken"
import "HybridCustody"
transaction(childAddress: Address, providerPath: PrivatePath, withdrawID: UInt64) {
    let providerRef: &{NonFungibleToken.Provider}
    prepare(signer: AuthAccount) {
        // Get a reference to the signer's HybridCustody.Manager from storage
        let managerRef: &HybridCustody.Manager = signer.borrow<&HybridCustody.Manager>(
                from: HybridCustody.ManagerStoragePath
            ) ?? panic("Could not borrow reference to HybridCustody.Manager in signer's account at expected path!")
        
        // Borrow a reference to the signer's specified child (proxy) account
        let account: &{AccountPublic, MetadataViews.Resolver} = managerRef.borrowAccount(addr: childAddress)
            ?? panic("Signer does not have access to specified account")
        
        // Get a reference to the child NFT Provider and assign to the transaction scope variable
        let cap: Capability = account.getCapability(
                path: providerPath,
                type: Type<&{NonFungibleToken.Provider}>()
            ) ?? panic("Cannot access NonFungibleToken.Provider from this child account")
        
        // We'll need to cast the Capability - this is possible thanks to CapabilityFactory, though we'll rely on the relevant
        // Factory having been configured for this Type or it won't be castable
        self.providerRef = cap as! Capability<&{NonFungibleToken.Provider}>
    }
    execute {
        // Withdraw the NFT from the Collection
        let nft <- self.providerRef.withdraw(withdrawID: withdrawID)
        // Do stuff with the NFT
        // ...
    }
}

At the end of this transaction, you withdrew an NFT from the specified account using a Provider Capability. A similar approach could get you reference to the linked account's

Revoking Secondary Access on a Linked Account

The expected uses of child accounts for progressive onboarding implies that they will be accounts with shared access. A user may decide that they no longer want secondary parties to have access to the child account.

There are two ways a party can have delegated access to an account - keys and AuthAccount Capability. With ProxyAccount mediated access, a user wouldn't be able to revoke anyone's access except for their own. With unrestricted access via ChildAccount, one could remove parents (ChildAccount.removeParent(parent: Address)) thereby unlinking relevant Capabilities and further destroying their ProxyAccount and CapabilityProxy resources.

Ultimately, things are not entirely straightforward with respect to AuthAccount Capabilities, at least not until Capability Controllers enter the picture. This is discussed in more detail in the Flip. For now, we recommend that if users want to revoke secondary access, they transfer any assets from the relevant child account and remove it from their Manager altogether.

Remove a Child Account

As mentioned above, if a user no longer wishes to share access with another party, it's recommended that desired assets be transferred from that account to either their main account or other linked accounts and the linked account be removed from their HybridCustody.Manager. Let's see how to complete that removal.

remove_child_account.cdc

import "HybridCustody"
transaction(child: Address) {
    prepare (acct: AuthAccount) {
        let manager = acct.borrow<&HybridCustody.Manager>(from: HybridCustody.ManagerStoragePath)
            ?? panic("manager not found")
        manager.removeChild(addr: child)
    }
}

After removal, the signer no longer has delegated access to the removed account via their Manager.

Objectives

Design Overview

Identifying Account Hierarchy​

Restricted vs. Owned Accounts​

Considerations​

Implementation

Examples​

Query Whether an Address Has Associated Accounts​

Query All Accounts Associated with Address​

Query All Owned NFT Metadata​

Query All Account FungibleToken Balances​

Access NFT in Child Account from Parent Account​

Revoking Secondary Access on a Linked Account​

Remove a Child Account​