Publish and Claim: Inbox API for Capability Bootstrapping

docs/language/accounts.mdx

@@ -94,6 +94,10 @@ to the `prepare` phase of the transaction.
 
       let keys: AuthAccount.Keys
 
+      // Provides a API for bootstrapping (sending and receiving) capabilities
+
+      let inbox: AuthAccount.Inbox
+
       // All the paths associated with this account
       let publicPaths: [PublicPath]
       let privatePaths: [PrivatePath]
@@ -165,6 +169,21 @@ to the `prepare` phase of the transaction.
           // Returns the revoked key if it exists, or nil otherwise.
           fun revoke(keyIndex: Int): AccountKey?
       }
+
+      struct Inbox {
+        // Publishes a new Capability under the given name, to be claimed by the specified recipient
+        fun publish(_ value: Capability, name: String, recipient: Address)
+
+        // Unpublishes a Capability previously published by this account.
+        // Returns `nil` if no Capability is published under the given name.
+        // Errors if the Capability under that name does not match the provided type.
+        fun unpublish<T: &Any>(_ name: String): Capability<T>?
+
+        // Claims a Capability previously published by the specified provider.
+        // Returns `nil` if no Capability is published under the given name, or if this account is not its intended recipient.
+        // Errors if the Capability under that name does not match the provided type.
+        fun claim<T: &Any>(_ name: String, provider: Address): Capability<T>?
+    }
   }
 
   struct DeployedContract {
@@ -321,6 +340,68 @@ transaction() {
 However, this method is deprecated and is available only for the backward compatibility.
 </Callout>
 
+## Account Inbox
+
+Accounts also possess an Inbox that can be used to make [Capabilities](capability-based-access-control) available to specific accounts. 
+The functions in this Inbox provide a convenient means to "bootstrap" Capabilities, 
+setting up an initial connection between two accounts that will later allow them to transfer data or permissions through a Capability.
+
+### Publishing a Capability
+
+An account (the Provider) that would like to provide a Capability to another account (the Recipient) can do so using the `publish` function:
+
+```cadence
+fun publish(_ value: Capability, name: String, recipient: Address)
+```
+
+This publishes the specified Capability using the provided string as an identifier, to be later claimed by the Recipient.
+Note, however, that until the Recipient does claim this Capability, it is stored on the Provider's account, 
+and contributes towards their Account Storage total. 
+
+Calling this function emits an event, `InboxValuePublished`, 
+that includes the address of both the Provider and the Recipient, as well as the name and the type of the published Capability.
+Refer to the [`Core Events` section](core-events#inbox-value-published) for more details on this event.
+
+### Claiming a Capability
+
+The intended Recipient of a Capability can claim that Capability from the Provider using the `claim` function: 
+
+```cadence 
+fun claim<T: &Any>(_ name: String, provider: Address): Capability<T>?
+```
+
+This looks up the specified name in the Provider's inbox, returning it to the Recipient if it is present, 
+conforms to the provided type argument, and is intended for the calling Recipient. 
+If the Provider has no Capability stored under the provided name, 
+or if the calling Recipient is not the intended recipient of the Capability, the function returns `nil`. 
+If the borrow type of the Capability is not a subtype of the provided type argument, the function will error at runtime. 
+
+Upon successful completion of the `claim` function, the claimed Capability is removed from the Provider's inbox. 
+Note that this means a given Capability can only be claimed once. 
+
+Calling this function emits an event, `InboxValueRemoved`, 
+that includes the address of both the Provider and the Recipient, as well as the name of the claimed Capability.
+Refer to the [`Core Events` section](core-events#inbox-value-removed) for more details on this event.
+
+### Unpublishing a Capability
+
+If the Provider of a Capability no longer wishes for it to be published for some reason (e.g. they no longer wish to pay for its storage costs),
+they can unpublish it using the `unpublish` function: 
+
+```cadence 
+fun unpublish<T: &Any>(_ name: String): Capability<T>?
+```
+
+This looks up the specified name in the Provider's inbox, returning it to the Provider if it is present and conforms to the provided type argument.
+If the Provider has no Capability stored under the provided name, the function returns `nil`. 
+If the borrow type of the Capability is not a subtype of the provided type argument, the function will error at runtime. 
+
+Upon successful completion of the `unpublish` function, the unpublished Capability is removed from the Provider's inbox. 
+
+Calling this function emits an event, `InboxValueRemoved`, 
+that includes the address of the Provider, and the name of the claimed Capability.
+Refer to the [`Core Events` section](core-events#inbox-value-removed) for more details on this event.
+
 ## Account Storage
 
 All accounts have storage.

docs/language/core-events.md

@@ -121,3 +121,51 @@ pub event AccountContractRemoved(
 | `address`   | `Address` | The address of the account the contract gets removed from |
 | `codeHash`  | `[UInt8]` | Hash of the contract source code                          |
 | `contract`  | `String`  | The name of the the contract                              |
+
+### Inbox Value Published
+
+Event that is emitted when a Capability is published from an account.
+
+Event name: `flow.InboxValuePublished`
+
+```cadence
+pub event InboxValuePublished(provider: Address, recipient: Address, name: String, type: Type) 
+```
+
+| Field             | Type      | Description                                  |
+| ----------------- | --------- | -------------------------------------------- |
+| `provider`        | `Address` | The address of the publishing account        |
+| `recipient`       | `Address` | The address of the intended recipient        |
+| `name`            | `String`  | The name associated with the published value |
+| `type`            | `Type`    | The type of the published value              |
+
+To reduce the potential for spam, 
+we recommend that user agents that display events do not display this event as-is to their users, 
+and allow users to restrict whom they see events from. 
+
+### Inbox Value Removed
+
+Event that is emitted when a Capability is removed from an account. 
+
+Event name: `flow.InboxValueRemoved`
+
+```cadence
+pub event InboxValueRemoved(provider: Address, remover: Address, name: String)
+```
+
+| Field           | Type      | Description                                  |
+| --------------- | --------- | -------------------------------------------- |
+| `provider`      | `Address` | The address of the publishing account        |
+| `remover`       | `Address` | The address of the removing account          |
+| `name`          | `String`  | The name associated with the published value |
+
+When this event is emitted by a call to `AuthAccount.Inbox.claim`, 
+the `provider` field of this event will be the original `provider` of the Capability, 
+and the `remover` field will be the claiming `recipient`. 
+
+When this event is emitted by a call to `AuthAccount.Inbox.unpublish`, 
+both the `provider` and the `remover` field of this event will be the original `provider` of the Capability. 
+
+To reduce the potential for spam, 
+we recommend that user agents that display events do not display this event as-is to their users, 
+and allow users to restrict whom they see events from. 

runtime/common/memorykind.go

@@ -52,6 +52,7 @@ const (
 	MemoryKindBoundFunctionValue
 	MemoryKindBigInt
 	MemoryKindSimpleCompositeValue
+	MemoryKindPublishedValue
 
 	// Atree Nodes
 	MemoryKindAtreeArrayDataSlab