Inbox
Accounts have an inbox, which allows making capabilities available to specific accounts. The inbox provides a convenient way to "bootstrap" capabilities: setting up an initial connection between two accounts, that the accounts can use to transfer data or perform actions.
An account exposes its inbox through the inbox field,
which has the type Account.Inbox.
Account.Inbox
_31access(all)_31struct Inbox {_31_31 /// Publishes a new Capability under the given name,_31 /// to be claimed by the specified recipient._31 access(Inbox | PublishInboxCapability)_31 fun publish(_ value: Capability, name: String, recipient: Address)_31_31 /// Unpublishes a Capability previously published by this account._31 ///_31 /// Returns `nil` if no Capability is published under the given name._31 ///_31 /// Errors if the Capability under that name does not match the provided type._31 access(Inbox | UnpublishInboxCapability)_31 fun unpublish<T: &Any>(_ name: String): Capability<T>?_31_31 /// Claims a Capability previously published by the specified provider._31 ///_31 /// Returns `nil` if no Capability is published under the given name,_31 /// or if this account is not its intended recipient._31 ///_31 /// Errors if the Capability under that name does not match the provided type._31 access(Inbox | ClaimInboxCapability)_31 fun claim<T: &Any>(_ name: String, provider: Address): Capability<T>?_31}_31_31entitlement Inbox_31_31entitlement PublishInboxCapability_31entitlement UnpublishInboxCapability_31entitlement ClaimInboxCapability
Publishing a capability to the account inbox
An account (the provider) that would like to provide a capability to another account (the recipient)
can do so using the publish function:
_10access(Inbox | PublishInboxCapability)_10fun publish(_ value: Capability, name: String, recipient: Address)
Calling the publish function requires access to an account via a reference which is authorized
with the coarse-grained Inbox entitlement (auth(Inbox) &Account),
or the fine-grained PublishInboxCapability entitlement (auth(PublishInboxCapability) &Account).
The function publishes the specified capability using the provided string as an identifier, to be later claimed by the recipient. Note, however, that until the recipient claims the capability, the provider's account stores it, and the capability contributes towards the provider's account storage usage.
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 page for more details on this event.
Claiming a capability from the account inbox
The intended recipient of a capability can claim a capability from the provider using the claim function:
_10access(Inbox | ClaimInboxCapability)_10fun claim<T: &Any>(_ name: String, provider: Address): Capability<T>?
Calling the claim function requires access to an account via a reference which is authorized
with the coarse-grained Inbox entitlement (auth(Inbox) &Account),
or the fine-grained ClaimInboxCapability entitlement (auth(ClaimInboxCapability) &Account).
If the provider's inbox has a capability stored under the provided name, the calling recipient is the intended recipient, and it conforms to the provided type argument, then the function removes the capability from the provider's inbox and returns it.
If the provider's inbox has no capability stored under the provided name,
or if the calling recipient is not the intended recipient,
the function returns nil.
If the borrow type of the capability is not a subtype of the provided type argument,
the program aborts.
It is only possible to claim a capability once.
Calling function claim function emits an event, InboxValueClaimed,
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 page for more details on this event.
Unpublishing a capability from the account inbox
If the provider no longer wishes to publish a capability for some reason,
they can unpublish the capability using the unpublish function:
_10access(Inbox | UnpublishInboxCapability)_10fun unpublish<T: &Any>(_ name: String): Capability<T>?
Calling the unpublish function requires access to an account via a reference which is authorized
with the coarse-grained Inbox entitlement (auth(Inbox) &Account),
or the fine-grained UnpublishInboxCapability entitlement (auth(UnpublishInboxCapability) &Account).
If the provider's inbox has a capability stored under the provided name, and it conforms to the provided type argument, then the function removes the capability from the inbox and returns it.
If the provider's inbox 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 program aborts.
Calling the unpublish function emits an event, InboxValueUnpublished,
that includes the address of the provider, and the name of the unpublished capability.
Refer to the Core Events page for more details on this event.