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

access(all)

struct Inbox {

/// Publishes a new Capability under the given name,

/// to be claimed by the specified recipient.

access(Inbox | PublishInboxCapability)

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.

access(Inbox | UnpublishInboxCapability)

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.

access(Inbox | ClaimInboxCapability)

fun claim<T: &Any>(_ name: String, provider: Address): Capability<T>?

}

entitlement Inbox

entitlement PublishInboxCapability

entitlement UnpublishInboxCapability

entitlement 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:

access(Inbox | PublishInboxCapability)

fun 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:

access(Inbox | ClaimInboxCapability)

fun 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.

info

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:

access(Inbox | UnpublishInboxCapability)

fun 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.