You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/language/accounts/inbox.mdx
+22-49Lines changed: 22 additions & 49 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,14 +3,9 @@ title: Inbox
3
3
sidebar_position: 6
4
4
---
5
5
6
-
Accounts have an inbox,
7
-
which allows making [capabilities](../capabilities.md) available to specific accounts.
8
-
The inbox provides a convenient way to "bootstrap" capabilities:
9
-
setting up an initial connection between two accounts,
10
-
that the accounts can use to transfer data or perform actions.
6
+
Accounts have an inbox, which allows making [capabilities] available to specific accounts. The inbox provides a convenient way to _bootstrap_ capabilities, which sets up an initial connection between two accounts that the accounts can use to transfer data or perform actions.
11
7
12
-
An account exposes its inbox through the `inbox` field,
13
-
which has the type `Account.Inbox`.
8
+
An account exposes its inbox through the `inbox` field, which has the type `Account.Inbox`.
An account (the provider) that would like to provide a capability to another account (the recipient)
54
-
can do so using the `publish` function:
48
+
An account (the provider) that would like to provide a capability to another account (the recipient) can do so using the `publish` function:
55
49
56
50
```cadence
57
51
access(Inbox | PublishInboxCapability)
58
52
fun publish(_ value: Capability, name: String, recipient: Address)
59
53
```
60
54
61
-
Calling the `publish` function requires access to an account via a reference which is authorized
62
-
with the coarse-grained `Inbox` entitlement (`auth(Inbox) &Account`),
63
-
or the fine-grained `PublishInboxCapability` entitlement (`auth(PublishInboxCapability) &Account`).
55
+
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`).
64
56
65
-
The function publishes the specified capability using the provided string as an identifier, to be later claimed by the recipient.
66
-
Note, however, that until the recipient claims the capability, the provider's account stores it,
67
-
and the capability contributes towards the provider's account storage usage.
57
+
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.
68
58
69
-
Calling this function emits an event, `InboxValuePublished`,
70
-
that includes the address of both the provider and the recipient, as well as the name and the type of the published capability.
71
-
Refer to the [Core Events page](../core-events.md#inbox-value-published) for more details on this event.
59
+
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 [Inbox Value Published] for more details on this event.
fun claim<T: &Any>(_ name: String, provider: Address): Capability<T>?
80
68
```
81
69
82
-
Calling the `claim` function requires access to an account via a reference which is authorized
83
-
with the coarse-grained `Inbox` entitlement (`auth(Inbox) &Account`),
84
-
or the fine-grained `ClaimInboxCapability` entitlement (`auth(ClaimInboxCapability) &Account`).
70
+
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`).
85
71
86
-
If the provider's inbox has a capability stored under the provided name,
87
-
the calling recipient is the intended recipient,
88
-
and it conforms to the provided type argument,
89
-
then the function removes the capability from the provider's inbox and returns it.
72
+
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.
90
73
91
-
If the provider's inbox has no capability stored under the provided name,
92
-
or if the calling recipient is not the intended recipient,
93
-
the function returns `nil`.
94
-
If the borrow type of the capability is not a subtype of the provided type argument,
95
-
the program aborts.
74
+
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.
96
75
97
76
:::tip
98
77
99
78
It is only possible to claim a capability once.
100
79
101
80
:::
102
81
103
-
Calling function `claim` function emits an event, `InboxValueClaimed`,
104
-
that includes the address of both the provider and the recipient,
105
-
as well as the name of the claimed capability.
106
-
Refer to the [Core Events page](../core-events.md#inbox-value-claimed) for more details on this event.
82
+
Calling the `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 [Inbox Value Claimed] for more details on this event.
107
83
108
84
## Unpublishing a capability from the account inbox
109
85
110
-
If the provider no longer wishes to publish a capability for some reason,
111
-
they can unpublish the capability using the `unpublish` function:
86
+
If the provider no longer wishes to publish a capability for some reason, they can unpublish the capability using the `unpublish` function:
112
87
113
88
```cadence
114
89
access(Inbox | UnpublishInboxCapability)
115
90
fun unpublish<T: &Any>(_ name: String): Capability<T>?
116
91
```
117
92
118
-
Calling the `unpublish` function requires access to an account via a reference which is authorized
119
-
with the coarse-grained `Inbox` entitlement (`auth(Inbox) &Account`),
120
-
or the fine-grained `UnpublishInboxCapability` entitlement (`auth(UnpublishInboxCapability) &Account`).
93
+
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`).
121
94
122
-
If the provider's inbox has a capability stored under the provided name,
123
-
and it conforms to the provided type argument,
124
-
then the function removes the capability from the inbox and returns it.
95
+
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.
125
96
126
-
If the provider's inbox has no capability stored under the provided name,
127
-
the function returns `nil`.
128
-
If the borrow type of the capability is not a subtype of the provided type argument,
129
-
the program aborts.
97
+
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.
130
98
131
-
Calling the `unpublish` function emits an event, `InboxValueUnpublished`,
132
-
that includes the address of the provider, and the name of the unpublished capability.
133
-
Refer to the [Core Events page](../core-events.md#inbox-value-unpublished) for more details on this event.
99
+
Calling the `unpublish` function emits an event, `InboxValueUnpublished`, which includes the address of the provider and the name of the unpublished capability. Refer to [Inbox Value Unpublished] for more details on this event.
Copy file name to clipboardExpand all lines: docs/language/accounts/keys.mdx
+25-43Lines changed: 25 additions & 43 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,14 +3,9 @@ title: Keys
3
3
sidebar_position: 4
4
4
---
5
5
6
-
Accounts have keys associated with them.
7
-
When a key is added to an account,
8
-
the key can be used to sign a [transaction](../transactions.md),
9
-
which in turn gets access the account
10
-
and can [perform write operations](./index.mdx#performing-write-operations) on it.
6
+
Accounts have keys associated with them. When a key is added to an account, the key can be used to sign a [transaction], which in turn gets access to the account and can [perform write operations] on it.
11
7
12
-
An account exposes its keys through the `keys` field,
13
-
which has the type `Account.Keys`.
8
+
An account exposes its keys through the `keys` field, which has the type `Account.Keys`.
14
9
15
10
## `Account.Keys`
16
11
@@ -24,7 +19,7 @@ struct Keys {
24
19
25
20
/// Returns the key at the given index, if it exists, or nil otherwise.
26
21
///
27
-
/// Revoked keys are always returned, but they have `isRevoked` field set to true.
22
+
/// Revoked keys are always returned, but they have an `isRevoked` field set to true.
28
23
access(all)
29
24
view fun get(keyIndex: Int): AccountKey?
30
25
@@ -91,48 +86,37 @@ struct AccountKey {
91
86
}
92
87
```
93
88
94
-
A valid account key's `publicKey` field is a `PublicKey` of either the
95
-
`ECDSA_P256` or `ECDSA_secp256k1` signature algorithm.
96
-
Public keys of other signature algorithms supported by Cadence are
97
-
not valid account public keys.
89
+
A valid account key's `publicKey` field is a `PublicKey` of either the `ECDSA_P256` or `ECDSA_secp256k1` signature algorithm. Public keys of other signature algorithms supported by Cadence are not valid account public keys.
98
90
99
-
Refer to the [public keys section](../crypto.mdx#public-keys)
100
-
for more details on the creation and validity of public keys.
91
+
Refer to the [public keys section] for more details on the creation and validity of public keys.
101
92
102
-
A valid account key's `hashAlgorithm` field is either `SHA2_256` or `SHA3_256`.
103
-
All other hash algorithms supported by Cadence are
104
-
not valid for hashing with an account key.
93
+
A valid account key's `hashAlgorithm` field is either `SHA2_256` or `SHA3_256`. All other hash algorithms supported by Cadence are not valid for hashing with an account key.
105
94
106
-
Refer to the [hash algorithms section](../crypto.mdx#hash-algorithms)
107
-
for more details on hash algorithms.
95
+
Refer to the [hash algorithms section] for more details on hash algorithms.
108
96
109
97
## Getting an account key
110
98
111
99
The functions `keys.get` and `keys.forEach` allow retrieving the keys of an account.
112
100
113
-
The `get` function allows retrieving a key with a specific index.
114
-
The function returns the key if it exists, and `nil` otherwise.
101
+
The `get` function allows retrieving a key with a specific index. The function returns the key if it exists, and `nil` otherwise:
115
102
116
103
```cadence
117
104
access(all)
118
105
view fun get(keyIndex: Int): AccountKey?
119
106
```
120
107
121
-
The `forEach` function allows iterating over all keys of an account.
108
+
The `forEach` function allows iterating over all keys of an account:
122
109
123
110
```cadence
124
111
access(all)
125
112
fun forEach(_ function: fun(AccountKey): Bool)
126
113
```
127
114
128
-
For each key of the account, the `forEach` function calls the given callback, passing the key to it.
129
-
When the callback function returns `true` the iteration continues,
130
-
and when it returns `false`, iteration stops.
115
+
For each key of the account, the `forEach` function calls the given callback, passing the key to it. When the callback function returns `true`, the iteration continues, and when it returns `false`, the iteration stops.
131
116
132
117
:::warning
133
118
134
-
The `keys.get` and `keys.forEach` functions include revoked keys,
135
-
which have the `isRevoked` field set to `true`.
119
+
The `keys.get` and `keys.forEach` functions include revoked keys, which have the `isRevoked` field set to `true`.
136
120
137
121
:::
138
122
@@ -155,7 +139,7 @@ fun main() {
155
139
156
140
## Adding an account key
157
141
158
-
The function `keys.add` allows a key to access an account.
142
+
The function `keys.add` allows a key to access an account:
159
143
160
144
```cadence
161
145
access(Keys | AddKey)
@@ -166,12 +150,9 @@ fun add(
166
150
): AccountKey
167
151
```
168
152
169
-
Calling the `add` function requires access to an account via a reference which is authorized
170
-
with the coarse-grained `Keys` entitlement (`auth(Keys) &Account`),
171
-
or the fine-grained `AddKey` entitlement (`auth(AddKey) &Account`).
153
+
Calling the `add` function requires access to an account via a reference, which is authorized with the coarse-grained `Keys` entitlement (`auth(Keys) &Account`), or the fine-grained `AddKey` entitlement (`auth(AddKey) &Account`).
172
154
173
-
For example, to add a public key to an existing account,
174
-
which signed the transaction:
155
+
For example, to add a public key to an existing account that signed the transaction:
A more complex transaction, which creates an account,
194
-
has the signer of the transaction pay for the account creation,
195
-
and authorizes one key to access the account,
196
-
could look like:
174
+
A more complex transaction, which creates an account, has the signer of the transaction pay for the account creation, and authorizes one key to access the account, could look like:
The `revoke` function revokes a key from accessing an account.
220
-
The function only marks the key at the given index as revoked, but never deletes it.
197
+
The `revoke` function revokes a key from accessing an account. The function only marks the key at the given index as revoked, but never deletes it:
221
198
222
199
```cadence
223
200
access(Keys | RevokeKey)
224
201
fun revoke(keyIndex: Int): AccountKey?
225
202
```
226
203
227
-
Calling the `revoke` function requires access to an account via a reference which is authorized
228
-
with the coarse-grained `Keys` entitlement (`auth(Keys) &Account`),
229
-
or the fine-grained `RevokeKey` entitlement (`auth(RevokeKey) &Account`).
204
+
Calling the `revoke` function requires access to an account via a reference, which is authorized with the coarse-grained `Keys` entitlement (`auth(Keys) &Account`), or the fine-grained `RevokeKey` entitlement (`auth(RevokeKey) &Account`).
230
205
231
-
For example, to revoke the third key of the account which signed the transaction:
206
+
For example, to revoke the third key of the account that signed the transaction:
0 commit comments