From fa58215c1b1df579e7a5bc486dfc95c7ae990106 Mon Sep 17 00:00:00 2001 From: Giovanni Sanchez <108043524+sisyphusSmiling@users.noreply.github.com> Date: Thu, 10 Oct 2024 11:04:32 -0700 Subject: [PATCH] update account linking docs --- .../guides/account-linking/child-accounts.md | 18 +++++++++--------- docs/build/guides/account-linking/index.md | 14 +++++++------- .../guides/account-linking/parent-accounts.md | 6 +++--- 3 files changed, 19 insertions(+), 19 deletions(-) diff --git a/docs/build/guides/account-linking/child-accounts.md b/docs/build/guides/account-linking/child-accounts.md index 426e38bd89..ec3da9624a 100644 --- a/docs/build/guides/account-linking/child-accounts.md +++ b/docs/build/guides/account-linking/child-accounts.md @@ -38,7 +38,7 @@ Very simply, account linking is a [feature in Cadence](https://github.com/onflow [Account](https://cadence-lang.org/docs/language/accounts#authaccount) create a [Capability](https://cadence-lang.org/docs/language/capabilities) on itself. -Below is an example demonstrating how to issue an `Account` Capability from a signing account +Below is an example demonstrating how to issue an `&Account` Capability from a signing account transaction: @@ -55,7 +55,7 @@ transaction(linkPathSuffix: String) { } ``` -From there, the signing account can retrieve the privately linked `Account` Capability and delegate it to another +From there, the signing account can retrieve the privately linked `&Account` Capability and delegate it to another account, revoking the Capability if they wish to revoke delegated access. Note that in order to link an account, a transaction must state the `#allowAccountLinking` pragma in the top line of the @@ -64,16 +64,16 @@ transaction that may create a Capability on their `Account`. ### Linking Accounts -Linking accounts leverages this account link, otherwise known as an **`Account` Capability**, and encapsulates it. The +Linking accounts leverages this account link, otherwise known as an **`&Account` 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 **Parent-Child accounts** - For the moment, we’ll call the account created by the app the “child” account and the -account receiving its `Account` Capability the “parent” account. Existing methods of account access & delegation (i.e. +account receiving its `&Account` Capability the “parent” account. Existing methods of account access & delegation (i.e. keys) still imply ownership over the account, but insofar as linked accounts are concerned, the account to which both -the user and the app share access via `Account` Capability will be considered the “child” account. +the user and the app share access via `&Account` Capability will be considered the “child” account. **Walletless onboarding** - An onboarding flow whereby an app creates a custodial account for a user, onboarding them to the app, obviating the need for user wallet authentication. @@ -86,7 +86,7 @@ account and linking it with the authenticated account, resulting in a "hybrid cu user access to that account has been mediated via account linking. **Account Linking** - Technically speaking, account linking in our context consists of giving some other account an -`Account` Capability from the granting account. This Capability is maintained in standardized resource called a +`&Account` Capability from the granting account. This Capability is maintained in standardized resource called a `HybridCustody.Manager`, providing its owning user access to any and all of their linked accounts. **Progressive Onboarding** - An onboarding flow that walks a user up to self-custodial ownership, starting with @@ -102,7 +102,7 @@ thereby giving the delegatee presiding authority superseding any other "restrict ## Account Linking -Linking an account is the process of delegating account access via `Account` Capability. Of course, we want to do this +Linking an account is the process of delegating account access via `&Account` 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 `HybridCustody` contract which we'll continue to use in this guidance. @@ -238,7 +238,7 @@ those NFTs so the user can easily transfer them between their linked accounts. #### Publish -Here, the account delegating access to itself links its `Account` Capability, and publishes it to be claimed by the +Here, the account delegating access to itself links its `&Account` Capability, and publishes it to be claimed by the designated parent account. ```cadence publish_to_parent.cdc @@ -694,7 +694,7 @@ either on the user's device or some backend KMS. ### App-Funded, User-Custodied In this case, the backend app account funds account creation, but adds a key to the account which the user custodies. In -order for the app to act on the user's behalf, it has to be delegated access via `Account` Capability which the backend +order for the app to act on the user's behalf, it has to be delegated access via `&Account` Capability which the backend app account would maintain in a `HybridCustody.Manager`. This means that the new account would have two parent accounts - the user's and the app. diff --git a/docs/build/guides/account-linking/index.md b/docs/build/guides/account-linking/index.md index b01ca1be96..c32fa2380d 100644 --- a/docs/build/guides/account-linking/index.md +++ b/docs/build/guides/account-linking/index.md @@ -43,22 +43,22 @@ another account programmatically without the need for an active key on the acces can be limited when creating a Capability so only intended functions or fields can be accessed. Account linking is made possible by the extension of Capabilities on the `Account` object itself. Similar to how storage -capabilities allow access to a value stored in an account's storage, `Account` capabilities allow delegated access to +capabilities allow access to a value stored in an account's storage, `&Account` Capabilities allow delegated access to the issuing `Account`. These Capabilities allow for access to key assignment, contract deployment, and other privileged actions on the delegating `Account` - effectively sharing ownership of the account without ever adding or sharing a key. This Capability can of course be revoked at any time by the delegating account. ### Creating Account Links -When referring to 'account linking' we mean that an `Account` Capability is created by the parent account and published -to another account. The account owning the `Account` Capability which was made available to another account is the child +When referring to 'account linking' we mean that an `&Account` Capability is created by the parent account and published +to another account. The account owning the `&Account` Capability which was made available to another account is the child account. The account in possession of the Capability given by the child account becomes its parent account. ![Account linking on Flow relational diagram](resources/account-linking-relational-diagram.png) A link between two existing accounts on Flow can be created in two steps: -1. A child account creates an `Account` Capability and publishes it to the parent account. +1. A child account creates an `&Account` Capability and publishes it to the parent account. 2. The parent account, claims that Capability and can access the child's account through it. ![Account linking steps on Flow](resources/account-linking-steps-high-level.png) @@ -67,7 +67,7 @@ These two steps are implemented in Cadence as two transactions: ************************************Create capability************************************ -The account B creates and publishes the `Account` Capability to the account A at the address `0x01` +The account B creates and publishes the `&Account` Capability to the account A at the address `0x01` ```cadence #allowAccountLinking @@ -150,12 +150,12 @@ Account linking is a _very_ powerful Cadence feature, and thus it must be treate we’ve discussed account linking between two accounts we own, even if the child account is managed by a third-party application. But, we can't make the same trust assumptions about custodial accounts in the real world. -Creating an `Account` Capability and publishing it to an account we don’t own means we are giving that account full +Creating an `&Account` Capability and publishing it to an account we don’t own means we are giving that account full access to our account. This should be seen as an anti-pattern. :::warning -Creating an `Account` Capability and sharing it with third-party account effectually the same as giving that person your +Creating an `&Account` Capability and sharing it with third-party account effectually the same as giving that person your account's private keys. ::: diff --git a/docs/build/guides/account-linking/parent-accounts.md b/docs/build/guides/account-linking/parent-accounts.md index ea3e128173..b1b603fa6c 100644 --- a/docs/build/guides/account-linking/parent-accounts.md +++ b/docs/build/guides/account-linking/parent-accounts.md @@ -78,7 +78,7 @@ This provides more granular revocation as each parent account has its own Capabi It's worth noting here that `ChildAccount` Capabilities enable access to the underlying account according to rules configured by the child account delegating access. The `ChildAccount` maintains these rules along with an `OwnedAccount` -Capability within which the `Account` Capability is stored. Anyone with access to the surface level `ChildAccount` +Capability within which the `&Account` Capability is stored. Anyone with access to the surface level `ChildAccount` can then access the underlying `Account`, but only according the pre-defined rule set. These rules are fundamentally a list of Types that can/cannot be retrieved from an account. @@ -106,7 +106,7 @@ access to anything other than the Types you declare as allowable. ::: As mentioned earlier, `Manager`s also maintain access to "owned" accounts - accounts which define unrestricted access as -they allow direct retrieval of encapsulated `Account` Capabilities. These owned accounts, found in `Manager.ownedAccounts`, +they allow direct retrieval of encapsulated `&Account` Capabilities. These owned accounts, found in `Manager.ownedAccounts`, are simply `OwnedAccount` Capabilities instead of `ChildAccount` Capabilities. ![HybridCustody Total Overview](./resources/hybrid_custody_low_level.png) @@ -397,7 +397,7 @@ similar approach could get you any allowable Capabilities from a signer's child 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 `Account` Capability. With +There are two ways a party can have delegated access to an account - keys and `&Account` Capability. With `ChildAccount` mediated access, a user wouldn't be able to revoke anyone's access except for their own. With unrestricted access via `OwnedAccount`, one could remove parents (`OwnedAccount.removeParent(parent: Address)`) thereby unlinking relevant Capabilities and further destroying their `ChildAccount` and `CapabilityDelegator` resources.