diff --git a/docs/concepts/account-linking/child-accounts.mdx b/docs/concepts/account-linking/child-accounts.mdx index 419faddd0d..f341453aad 100644 --- a/docs/concepts/account-linking/child-accounts.mdx +++ b/docs/concepts/account-linking/child-accounts.mdx @@ -9,7 +9,7 @@ mediate the user’s on-chain actions on their behalf, and later delegate access user’s wallet. We’ll refer to this custodial pattern as the Hybrid Custody Model and the process of delegating control of the dApp account as Account Linking. -We'll cover: +## Objectives - Create a [walletless onboarding](https://flow.com/post/flow-blockchain-mainstream-adoption-easy-onboarding-wallets) transaction @@ -20,11 +20,11 @@ We'll cover: wallet-mediated “parent” account and any hybrid custody model “child” accounts - Facilitate transactions acting on assets in child accounts -# Point of Clarity +## Point of Clarity Before diving in, let's make a distinction between **"account linking"** and **"linking accounts"**. -## Account Linking +### Account Linking @@ -64,13 +64,13 @@ Note that in order to link an account, a transaction must state the `#allowAccou transaction. This is an interim safety measure so that wallet providers can notify users they're about to sign a transaction that may create a Capability on their AuthAccount. -## Linking Accounts +### Linking Accounts Linking accounts leverages this account link, otherwise known as an **AuthAccount Capability**, and encapsulates it. The [components and actions](https://github.com/onflow/flips/pull/72) involved in this process - what the Capability is encapsulated in, the collection that holds those encapsulations, etc. is what we'll dive into in this doc. -# Terminology +## Terminology **Parent-Child accounts** - For the moment, we’ll call the account created by the dApp the “child” account and the account receiving its AuthAccount Capability the “parent” account. Existing methods of account access & delegation (i.e. @@ -102,14 +102,14 @@ be expanding on later. **Owned Account** - An account delegation where the delegatee has unrestricted access on the delegating child account, thereby giving the delegatee presiding authority superseding any other "restricted" parent accounts. -# Account Linking +## Account Linking Linking an account is the process of delegating account access via AuthAccount Capability. Of course, we want to do this in a way that allows the receiving account to maintain that Capability and allows easy identification of the accounts on either end of the linkage - the user's main "parent" account and the linked "child" account. This is accomplished in the (still in flux) `HybridCustody` contract which we'll continue to use in this guidance. -## Pre-requisites +### Pre-requisites Since account delegation is mediated by developer-defined rules, you should make sure to first configure the resources that contain those rules. Contracts involved in defining and enforcing this ruleset are @@ -197,7 +197,7 @@ transaction { } ``` -![resources/hybrid_custody_high_level](resources/hybrid_custody_high_level.png) +![resources/hybrid_custody_high_level](./resources/hybrid_custody_high_level.png) *In this scenario, a user custodies a key for their main account which maintains access to a wrapped AuthAccount Capability, providing the user restricted access on the app account. The dApp maintains custodial access to the account @@ -226,9 +226,9 @@ those NFTs so the user can easily transfer them between their linked accounts. -## Publish & Claim +### Publish & Claim -### Publish +#### Publish Here, the account delegating access to itself links its AuthAccount Capability, and publishes it to be claimed by the account it will be linked to. @@ -255,7 +255,7 @@ transaction(parent: Address, factoryAddress: Address, filterAddress: Address) { } ``` -### Claim +#### Claim On the other side, the receiving account claims the published `ChildAccount` Capability, adding it to the signer's `HybridCustody.Manager.childAccounts` indexed on the child account's Address. @@ -304,7 +304,7 @@ transaction(childAddress: Address, filterAddress: Address?, filterPath: PublicPa } ``` -### Multi-Signed Transaction +#### Multi-Signed Transaction We can combine the two transactions in [Publish](#publish) and [Claim](#claim) into a single multi-signed transaction to achieve Hybrid Custody in a single step. @@ -406,7 +406,7 @@ transaction(parentFilterAddress: Address?, childAccountFactoryAddress: Address, } ``` -# Onboarding Flows +## Onboarding Flows Given the ability to establish an account and later delegate access to a user, dApps are freed from the constraints of dichotomous custodial & self-custodial paradigms. A developer can choose to onboard a user via traditional Web2 identity @@ -415,9 +415,9 @@ outset, creating a dApp-specific account & linking with the user’s wallet acco are known as walletless and blockchain-native onboarding respectively. Developers can choose to implement one for simplicity or both for maximum flexibility. -## Walletless Onboarding +### Walletless Onboarding -### Account Creation +#### Account Creation The following transaction creates an account, funding creation via the signer and adding the provided public key. You'll notice this transaction is pretty much your standard account creation. The magic for you will be how you custody the key @@ -479,7 +479,7 @@ transaction(pubKey: String, initialFundingAmt: UFix64) { } ``` -## Blockchain-Native Onboarding +### Blockchain-Native Onboarding This onboarding flow is really a single-transaction composition of the steps covered above. This is a testament to the power of the complex transactions you can compose on Flow with Cadence! @@ -494,7 +494,7 @@ Recall the [pre-requisites](#pre-requisites) needed to be satisfied before linki -### Account Creation & Linking +#### Account Creation & Linking Compared to walletless onboarding where a user does not have a Flow account, blockchain-native onboarding assumes a user already has a wallet configured and immediately links it with a newly created dApp account. This enables the dApp to @@ -640,7 +640,7 @@ transaction( } ``` -# Funding & Custody Patterns +## Funding & Custody Patterns Aside from implementing onboarding flows & account linking, you'll want to also consider the account funding & custodial pattern appropriate for the dApp you're building. The only pattern compatible with walletless onboarding (and therefore @@ -659,13 +659,13 @@ building in crypto. Here are the patterns you might consider: -## DApp-Funded, DApp-Custodied +### DApp-Funded, DApp-Custodied If you want to implement walletless onboarding, you can stop here as this is the only compatible pattern. In this scenario, a backend dApp account funds the creation of a new account and the dApp custodies the key for said account either on the user's device or some backend KMS. -## DApp-Funded, User-Custodied +### DApp-Funded, User-Custodied In this case, the backend dApp account funds account creation, but adds a key to the account which the user custodies. In order for the dApp to act on the user's behalf, it has to be delegated access via AuthAccount Capability which the @@ -675,14 +675,14 @@ account, this pattern may present unique considerations and edge cases for you a child account. Also note that this and the following patterns are incompatible with walletless onboarding in that the user must have a wallet. -## User-Funded, DApp-Custodied +### User-Funded, DApp-Custodied As mentioned above, this pattern unlocks totally service-less architectures - just a local client & smart contracts. An authenticated user signs a transaction creating an account, adding the key provided by the client, and linking the account as a child account. At the end of the transaction, hybrid custody is achieved and the dApp can sign with the custodied key on the user's behalf using the newly created account. -## User-Funded, User-Custodied +### User-Funded, User-Custodied While perhaps not useful for most dApps, this pattern may be desirable for advanced users who wish to create a shared access account themselves. The user funds account creation, adding keys they custody, and delegates secondary access to diff --git a/docs/concepts/account-linking/parent-accounts.mdx b/docs/concepts/account-linking/parent-accounts.mdx index a6429d62ea..c38153a0b6 100644 --- a/docs/concepts/account-linking/parent-accounts.mdx +++ b/docs/concepts/account-linking/parent-accounts.mdx @@ -72,7 +72,7 @@ and an account is a child account if it contains at minimum an `OwnedAccount` or Within a user's `Manager`, its mapping of `childAccounts` points to the addresses of its child accounts in each index, with corresponding values giving the Manager access to those accounts via corresponding`ChildAccount` Capability. -![HybridCustody Conceptual Overview](resources/hybrid_custody_conceptual_overview.png) +![HybridCustody Conceptual Overview](./resources/hybrid_custody_conceptual_overview.png) Likewise, the child account's `ChildAccount.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