Skip to content

Commit

Permalink
fixed codeblocks in lists
Browse files Browse the repository at this point in the history
  • Loading branch information
bjartek committed Feb 27, 2023
1 parent 034225d commit 391c4db
Show file tree
Hide file tree
Showing 3 changed files with 535 additions and 423 deletions.
124 changes: 73 additions & 51 deletions docs/language/capability-based-access-control.md
Expand Up @@ -31,93 +31,112 @@ This allows exposing and hiding certain functionality of a stored object.

Capabilities are created using the `link` function of an authorized account (`AuthAccount`):

- `cadence•fun link<T: &Any>(_ newCapabilityPath: CapabilityPath, target: Path): Capability<T>?`
-
```cadence
fun link<T: &Any>(_ newCapabilityPath: CapabilityPath, target: Path): Capability<T>?
```

`newCapabilityPath` is the public or private path identifying the new capability.
`newCapabilityPath` is the public or private path identifying the new capability.

`target` is any public, private, or storage path that leads to the object
that will provide the functionality defined by this capability.
`target` is any public, private, or storage path that leads to the object
that will provide the functionality defined by this capability.

`T` is the type parameter for the capability type.
A type argument for the parameter must be provided explicitly.
`T` is the type parameter for the capability type.
A type argument for the parameter must be provided explicitly.

The type parameter defines how the capability can be borrowed,
i.e., how the stored value can be accessed.
The type parameter defines how the capability can be borrowed,
i.e., how the stored value can be accessed.

The link function returns `nil` if a link for the given capability path already exists,
or the newly created capability if not.
The link function returns `nil` if a link for the given capability path already exists,
or the newly created capability if not.

It is not necessary for the target path to lead to a valid object;
the target path could be empty, or could lead to an object
which does not provide the necessary type interface:
It is not necessary for the target path to lead to a valid object;
the target path could be empty, or could lead to an object
which does not provide the necessary type interface:

The link function does **not** check if the target path is valid/exists at the time
the capability is created and does **not** check if the target value conforms to the given type.
The link function does **not** check if the target path is valid/exists at the time
the capability is created and does **not** check if the target value conforms to the given type.

The link is latent.
The target value might be stored after the link is created,
and the target value might be moved out after the link has been created.
The link is latent.
The target value might be stored after the link is created,
and the target value might be moved out after the link has been created.

Capabilities can be removed using the `unlink` function of an authorized account (`AuthAccount`):

- `cadence•fun unlink(_ path: CapabilityPath)`
-
```cadence
fun unlink(_ path: CapabilityPath)
```

`path` is the public or private path identifying the capability that should be removed.
`path` is the public or private path identifying the capability that should be removed.

To get the target path for a capability, the `getLinkTarget` function
of an authorized account (`AuthAccount`) or public account (`PublicAccount`) can be used:

- `cadence•fun getLinkTarget(_ path: CapabilityPath): Path?`

`path` is the public or private path identifying the capability.
The function returns the link target path,
if a capability exists at the given path,
or `nil` if it does not.
-
```cadence
fun getLinkTarget(_ path: CapabilityPath): Path?
```

`path` is the public or private path identifying the capability.
The function returns the link target path,
if a capability exists at the given path,
or `nil` if it does not.

Existing capabilities can be obtained by using the `getCapability` function
of authorized accounts (`AuthAccount`) and public accounts (`PublicAccount`):

- `cadence•fun getCapability<T>(_ at: CapabilityPath): Capability<T>`
-
```cadence
fun getCapability<T>(_ at: CapabilityPath): Capability<T>
```

For public accounts, the function returns a capability
if the given path is public.
It is not possible to obtain private capabilities from public accounts.
If the path is private or a storage path, the function returns `nil`.
For public accounts, the function returns a capability
if the given path is public.
It is not possible to obtain private capabilities from public accounts.
If the path is private or a storage path, the function returns `nil`.

For authorized accounts, the function returns a capability
if the given path is public or private.
If the path is a storage path, the function returns `nil`.
For authorized accounts, the function returns a capability
if the given path is public or private.
If the path is a storage path, the function returns `nil`.

`T` is the type parameter that specifies how the capability can be borrowed.
The type argument is optional, i.e. it need not be provided.
`T` is the type parameter that specifies how the capability can be borrowed.
The type argument is optional, i.e. it need not be provided.

The `getCapability` function does **not** check if the target exists.
The link is latent.
The `check` function of the capability can be used to check if the target currently exists and could be borrowed,

- `cadence•fun check<T: &Any>(): Bool`
-
```cadence
fun check<T: &Any>(): Bool
```

`T` is the type parameter for the reference type.
A type argument for the parameter must be provided explicitly.
`T` is the type parameter for the reference type.
A type argument for the parameter must be provided explicitly.

The function returns true if the capability currently targets an object
that satisfies the given type, i.e. could be borrowed using the given type.
The function returns true if the capability currently targets an object
that satisfies the given type, i.e. could be borrowed using the given type.

Finally, the capability can be borrowed to get a reference to the stored object.
This can be done using the `borrow` function of the capability:

- `cadence•fun borrow<T: &Any>(): T?`
-
```cadence
fun borrow<T: &Any>(): T?
```

The function returns a reference to the object targeted by the capability,
provided it can be borrowed using the given type.
The function returns a reference to the object targeted by the capability,
provided it can be borrowed using the given type.

`T` is the type parameter for the reference type.
If the function is called on a typed capability, the capability's type is used when borrowing.
If the capability is untyped, a type argument must be provided explicitly in the call to `borrow`.
`T` is the type parameter for the reference type.
If the function is called on a typed capability, the capability's type is used when borrowing.
If the capability is untyped, a type argument must be provided explicitly in the call to `borrow`.

The function returns `nil` when the targeted path is empty, i.e. nothing is stored under it.
When the requested type exceeds what is allowed by the capability (or any interim capabilities),
execution will abort with an error.
The function returns `nil` when the targeted path is empty, i.e. nothing is stored under it.
When the requested type exceeds what is allowed by the capability (or any interim capabilities),
execution will abort with an error.

```cadence
// Declare a resource interface named `HasCount`, that has a field `count`
Expand Down Expand Up @@ -229,6 +248,9 @@ let counterRef2 = publicAccount.borrow<&Counter>(from: /storage/counter)

The address of a capability can be obtained from the `address` field of the capability:

- `cadence•let address: Address`
-
```cadence
let address: Address
```

The address of the capability.
The address of the capability.
8 changes: 6 additions & 2 deletions docs/language/crypto.mdx
Expand Up @@ -261,7 +261,9 @@ The PoP can only be verified using the `PublicKey` method `verifyPoP`.

### BLS signature aggregation

`cadence•fun aggregateSignatures(_ signatures: [[UInt8]]): [UInt8]?`
```cadence
fun aggregateSignatures(_ signatures: [[UInt8]]): [UInt8]?
```

Aggregates multiple BLS signatures into one.
Signatures could be generated from the same or distinct messages, they
Expand All @@ -276,7 +278,9 @@ verfiy multiple signatures of the same message.

### BLS public key aggregation

`cadence•fun aggregatePublicKeys(_ publicKeys: [PublicKey]): PublicKey?`
```cadence
fun aggregatePublicKeys(_ publicKeys: [PublicKey]): PublicKey?
```

Aggregates multiple BLS public keys into one.

Expand Down

0 comments on commit 391c4db

Please sign in to comment.