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
It should be noted that not every library or tool may have every section, and that’s ok. This is purely a guide to help kickstart helpful documentation, not a strict pattern to follow.
Copy file name to clipboardExpand all lines: content/contracts-cairo/2.x/index.mdx
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,8 +8,8 @@ title: Contracts for Cairo
8
8
9
9
10
10
**A library for secure smart contract development** written in Cairo for [Starknet][starknet]. This library consists of a set of
11
-
[reusable components](/contracts-cairo/2.x/components) to build custom smart contracts, as well as ready-to-deploy [presets](/contracts-cairo/2.x/presets). You can also
12
-
find other [utilities](/contracts-cairo/2.x/api/utilities) including [interfaces and dispatchers](/contracts-cairo/alpha/interfaces) and [test utilities](/contracts-cairo/2.x/api/testing)
11
+
[reusable components](/contracts-cairo/2.x/components) to build custom smart contracts, as well as ready-to-deploy [presets](/contracts-cairo/2.x/presets). It also provides
12
+
helpful [utilities](/contracts-cairo/2.x/api/utilities) and [test utilities](/contracts-cairo/2.x/api/testing)
Copy file name to clipboardExpand all lines: content/contracts-cairo/3.x/access.mdx
+13-13Lines changed: 13 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -13,13 +13,13 @@ The most common and basic form of access control is the concept of ownership: th
13
13
of a contract and can do administrative tasks on it.
14
14
This approach is perfectly reasonable for contracts that have a single administrative user.
15
15
16
-
OpenZeppelin Contracts for Cairo provides [OwnableComponent](/contracts-cairo/alpha/api/access#OwnableComponent) for implementing ownership in your contracts.
16
+
OpenZeppelin Contracts for Cairo provides [OwnableComponent](/contracts-cairo/3.x/api/access#OwnableComponent) for implementing ownership in your contracts.
17
17
18
18
### Usage
19
19
20
20
Integrating this component into a contract first requires assigning an owner.
21
21
The implementing contract’s constructor should set the initial owner by passing the owner’s address to Ownable’s
22
-
[`initializer`](/contracts-cairo/alpha/api/access#OwnableComponent-initializer) like this:
22
+
[`initializer`](/contracts-cairo/3.x/api/access#OwnableComponent-initializer) like this:
23
23
24
24
```rust
25
25
#[starknet::contract]
@@ -106,7 +106,7 @@ will no longer be callable!
106
106
### Two step transfer
107
107
108
108
The component also offers a more robust way of transferring ownership via the
109
-
[OwnableTwoStepImpl](/contracts-cairo/alpha/api/access#OwnableComponent-Embeddable-Impls-OwnableTwoStepImpl) implementation. A two step transfer mechanism helps
109
+
[OwnableTwoStepImpl](/contracts-cairo/3.x/api/access#OwnableComponent-Embeddable-Impls-OwnableTwoStepImpl) implementation. A two step transfer mechanism helps
110
110
to prevent unintended and irreversible owner transfers. Simply replace the `OwnableMixinImpl`
111
111
with its respective two step variant:
112
112
@@ -146,7 +146,7 @@ flexibility in this regard.
146
146
147
147
In essence, we will be defining multiple roles, each allowed to perform different sets of actions.
148
148
An account may have, for example, 'moderator', 'minter' or 'admin' roles, which you will then check for
149
-
instead of simply using [`assert_only_owner`](/contracts-cairo/alpha/api/access#OwnableComponent-assert_only_owner). This check can be enforced through [`assert_only_role`](/contracts-cairo/alpha/api/access#AccessControlComponent-assert_only_role).
149
+
instead of simply using [`assert_only_owner`](/contracts-cairo/3.x/api/access#OwnableComponent-assert_only_owner). This check can be enforced through [`assert_only_role`](/contracts-cairo/3.x/api/access#AccessControlComponent-assert_only_role).
150
150
Separately, you will be able to define rules for how accounts can be granted a role, have it revoked, and more.
151
151
152
152
Most software uses access control systems that are role-based: some users are regular users, some may be supervisors
@@ -158,7 +158,7 @@ For each role that you want to define, you will create a new _role identifier_ t
158
158
check if an account has that role. See [Creating role identifiers](#creating-role-identifiers) for information
159
159
on creating identifiers.
160
160
161
-
Here’s a simple example of implementing [AccessControl](/contracts-cairo/alpha/api/access#AccessControlComponent) on a portion of an ERC20 token contract which defines
161
+
Here’s a simple example of implementing [AccessControl](/contracts-cairo/3.x/api/access#AccessControlComponent) on a portion of an ERC20 token contract which defines
162
162
and sets a 'minter' role:
163
163
164
164
```rust
@@ -242,12 +242,12 @@ mod MyContract {
242
242
```
243
243
244
244
<Callouttype='warn'>
245
-
Make sure you fully understand how [AccessControl](/contracts-cairo/alpha/api/access#AccessControlComponent) works before
245
+
Make sure you fully understand how [AccessControl](/contracts-cairo/3.x/api/access#AccessControlComponent) works before
246
246
using it on your system, or copy-pasting the examples from this guide.
247
247
</Callout>
248
248
249
249
While clear and explicit, this isn’t anything we wouldn’t have been able to achieve with
250
-
[Ownable](/contracts-cairo/alpha/api/access#OwnableComponent). Where [AccessControl](/contracts-cairo/alpha/api/access#AccessControlComponent) shines the most is in scenarios where granular
250
+
[Ownable](/contracts-cairo/3.x/api/access#OwnableComponent). Where [AccessControl](/contracts-cairo/3.x/api/access#AccessControlComponent) shines the most is in scenarios where granular
251
251
permissions are required, which can be implemented by defining _multiple_ roles.
252
252
253
253
Let’s augment our ERC20 token example by also defining a 'burner' role, which lets accounts destroy tokens:
@@ -350,16 +350,16 @@ security practice. Note that each account may still have more than one role, if
350
350
351
351
### Granting and revoking roles
352
352
353
-
The ERC20 token example above uses [`_grant_role`](/contracts-cairo/alpha/api/access#AccessControlComponent-_grant_role),
353
+
The ERC20 token example above uses [`_grant_role`](/contracts-cairo/3.x/api/access#AccessControlComponent-_grant_role),
354
354
an `internal` function that is useful when programmatically assigning
355
355
roles (such as during construction). But what if we later want to grant the 'minter' role to additional accounts?
356
356
357
357
By default, **accounts with a role cannot grant it or revoke it from other accounts**: all having a role does is making
358
-
the [`assert_only_role`](/contracts-cairo/alpha/api/access#AccessControlComponent-assert_only_role) check pass. To grant and revoke roles dynamically, you will need help from the role’s _admin_.
358
+
the [`assert_only_role`](/contracts-cairo/3.x/api/access#AccessControlComponent-assert_only_role) check pass. To grant and revoke roles dynamically, you will need help from the role’s _admin_.
359
359
360
360
Every role has an associated admin role, which grants permission to call the
361
-
[`grant_role`](/contracts-cairo/alpha/api/access#AccessControlComponent-grant_role) and
A role can be granted or revoked by using these if the calling account has the corresponding admin role.
364
364
Multiple roles may have the same admin role to make management easier.
365
365
A role’s admin can even be the same role itself, which would cause accounts with that role to be able
@@ -369,9 +369,9 @@ This mechanism can be used to create complex permissioning structures resembling
369
369
provides an easy way to manage simpler applications. `AccessControl` includes a special role with the role identifier
370
370
of `0`, called `DEFAULT_ADMIN_ROLE`, which acts as the **default admin role for all roles**.
371
371
An account with this role will be able to manage any other role, unless
372
-
[`set_role_admin`](/contracts-cairo/alpha/api/access#AccessControlComponent-set_role_admin) is used to select a new admin role.
372
+
[`set_role_admin`](/contracts-cairo/3.x/api/access#AccessControlComponent-set_role_admin) is used to select a new admin role.
373
373
374
-
Since it is the admin for all roles by default, and in fact it is also its own admin, this role carries significant risk. To mitigate this risk we provide [AccessControlDefaultAdminRules](/contracts-cairo/alpha/api/access#AccessControlDefaultAdminRulesComponent), a recommended extension of AccessControl that adds a number of enforced security measures for this role: the admin is restricted to a single account, with a 2-step transfer procedure with a delay in between steps.
374
+
Since it is the admin for all roles by default, and in fact it is also its own admin, this role carries significant risk. To mitigate this risk we provide [AccessControlDefaultAdminRules](/contracts-cairo/3.x/api/access#AccessControlDefaultAdminRulesComponent), a recommended extension of AccessControl that adds a number of enforced security measures for this role: the admin is restricted to a single account, with a 2-step transfer procedure with a delay in between steps.
375
375
376
376
Let’s take a look at the ERC20 token example, this time taking advantage of the default admin role:
For detailed information on the usage and implementation check the [API Reference](/contracts-cairo/alpha/api/account) section.
16
+
For detailed information on the usage and implementation check the [API Reference](/contracts-cairo/3.x/api/account) section.
17
17
</Callout>
18
18
19
19
## What is an account?
@@ -97,11 +97,11 @@ Starknet native account abstraction pattern allows for the creation of custom ac
97
97
usually most account implementations validate transactions using the [Stark curve](https://docs.starknet.io/learn/protocol/cryptography#the-stark-curve) which is the most efficient way
98
98
of validating signatures since it is a STARK-friendly curve.
99
99
100
-
OpenZeppelin Contracts for Cairo provides [AccountComponent](/contracts-cairo/alpha/api/account#AccountComponent) for implementing this validation scheme.
100
+
OpenZeppelin Contracts for Cairo provides [AccountComponent](/contracts-cairo/3.x/api/account#AccountComponent) for implementing this validation scheme.
101
101
102
102
### Usage
103
103
104
-
Constructing an account contract requires integrating both [AccountComponent](/contracts-cairo/alpha/api/account#AccountComponent) and [SRC5Component](/contracts-cairo/alpha/api/introspection#SRC5Component). The contract should also set up the constructor to initialize the public key that will be used as the account’s signer. Here’s an example of a basic contract:
104
+
Constructing an account contract requires integrating both [AccountComponent](/contracts-cairo/3.x/api/account#AccountComponent) and [SRC5Component](/contracts-cairo/3.x/api/introspection#SRC5Component). The contract should also set up the constructor to initialize the public key that will be used as the account’s signer. Here’s an example of a basic contract:
105
105
106
106
```rust
107
107
#[starknet::contract(account)]
@@ -180,11 +180,11 @@ pub trait AccountABI {
180
180
## Ethereum Account
181
181
182
182
Besides the Stark-curve account, OpenZeppelin Contracts for Cairo also offers Ethereum-flavored accounts that use the [secp256k1](https://en.bitcoin.it/wiki/Secp256k1) curve for signature validation.
183
-
For this the [EthAccountComponent](/contracts-cairo/alpha/api/account#EthAccountComponent) must be used.
183
+
For this the [EthAccountComponent](/contracts-cairo/3.x/api/account#EthAccountComponent) must be used.
184
184
185
185
### Usage
186
186
187
-
Constructing a secp256k1 account contract also requires integrating both [EthAccountComponent](/contracts-cairo/alpha/api/account#EthAccountComponent) and [SRC5Component](/contracts-cairo/alpha/api/introspection#SRC5Component).
187
+
Constructing a secp256k1 account contract also requires integrating both [EthAccountComponent](/contracts-cairo/3.x/api/account#EthAccountComponent) and [SRC5Component](/contracts-cairo/3.x/api/introspection#SRC5Component).
188
188
The contract should also set up the constructor to initialize the public key that will be used as the account’s signer.
Maximum time in seconds for an increase to [default\_admin\_delay](#IAccessControlDefaultAdminRules-default_admin_delay) (that is scheduled using [change\_default\_admin\_delay](#IAccessControlDefaultAdminRules-change_default_admin_delay)) to take effect. Defaults to 5 days.
405
-
406
-
When the [default\_admin\_delay](#IAccessControlDefaultAdminRules-default_admin_delay) is scheduled to be increased, it goes into effect after the new delay has passed with the purpose of giving enough time for reverting any accidental change (i.e. using milliseconds instead of seconds) that may lock the contract. However, to avoid excessive schedules, the wait is capped by this function and it can be overridden for a custom [default\_admin\_delay](#IAccessControlDefaultAdminRules-default_admin_delay) increase scheduling.
405
+
Maximum time in seconds for an increase to [default\_admin\_delay](#IAccessControlDefaultAdminRules-default_admin_delay) (that is scheduled using [change\_default\_admin\_delay](#IAccessControlDefaultAdminRules-change_default_admin_delay)) to take effect.
407
406
407
+
<Callouttype='warn'>
408
408
Make sure to add a reasonable amount of time while overriding this value, otherwise, there’s a risk of setting a high new delay that goes into effect almost immediately without the possibility of human intervention in the case of an input error (e.g. set milliseconds instead of seconds).
409
+
</Callout>
410
+
411
+
Consider carefully the value set for `MAXIMUM_DEFAULT_ADMIN_TRANSFER_DELAY` too, since it will affect how fast you can recover from an accidental delay increase.
Maximum time in seconds for a `default_admin` transfer delay.
420
+
421
+
<Callouttype='warn'>
422
+
If `MAXIMUM_DEFAULT_ADMIN_TRANSFER_DELAY` is set too high, you might be unable to recover from an accidental delay increase for an extended period. Too low, and it unnecessarily restricts how much security delay you can impose for `default_admin` transfers. As a best practice, consider setting it in the 30-60 day range for a good balance between security and recoverability.
Maximum time in seconds for a `default_admin` transfer delay.
1393
+
1394
+
<Callouttype='warn'>
1395
+
If `MAXIMUM_DEFAULT_ADMIN_TRANSFER_DELAY` is set too high, you might be unable to recover from an accidental delay increase for an extended period. Too low, and it unnecessarily restricts how much security delay you can impose for `default_admin` transfers. As a best practice, consider setting it in the 30-60 day range for a good balance between security and recoverability.
Copy file name to clipboardExpand all lines: content/contracts-cairo/3.x/api/erc20.mdx
+2Lines changed: 2 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1139,6 +1139,8 @@ Allows contracts to hook logic into deposit and withdraw transactions. This is w
1139
1139
1140
1140
ERC4626 preview methods must be inclusive of any entry or exit fees. Fees are calculated using [FeeConfigTrait](#ERC4626Component-FeeConfigTrait) methods and automatically adjust the final asset and share amounts. Fee transfers are handled in `ERC4626HooksTrait` methods.
1141
1141
1142
+
When a vault implements fees on deposits or withdrawals (either in shares or assets), fee transfers must be handled in these hooks by library clients. This creates a non-atomic operation flow consisting of multiple state-changing steps: transferring assets, minting or burning shares, and transferring (or minting) fees. Between these steps, the vault's state is temporarily inconsistent: the asset-to-share conversion rate does not accurately reflect the vault's final state until all steps have completed. Therefore, it is critical to avoid making any external calls (including to the vault contract itself) or querying conversion rates during hook execution.
1143
+
1142
1144
Special care must be taken when calling external contracts in these hooks. In that case, consider implementing reentrancy protections. For example, in the `withdraw` flow, the `withdraw_limit` is checked **before** the `before_withdraw` hook is invoked. If this hook performs a reentrant call that invokes `withdraw` again, the subsequent check on `withdraw_limit` will be done before the first withdrawal's core logic (e.g., burning shares and transferring assets) is executed. This could lead to bypassing withdrawal constraints or draining funds.
1143
1145
1144
1146
See the [ERC4626AssetsFeesMock](https://github.com/OpenZeppelin/cairo-contracts/tree/main/packages/test_common/src/mocks/erc4626.cairo#L253) and [ERC4626SharesFeesMock](https://github.com/OpenZeppelin/cairo-contracts/tree/main/packages/test_common/src/mocks/erc4626.cairo#L426) examples.
0 commit comments