Access API Reference
This page documents the public API of openzeppelin_access for OpenZeppelin Contracts for Sui v1.x.
use openzeppelin_access::access_control;Role-based access control registry for Sui Move packages. The root role is the consumer module's One-Time Witness (OTW), and managed roles must be defined in the same module as the root role.
The registry must be created from a module init during the first publish of the package that defines RootRole. Package upgrades do not run init for newly-added modules.
The module supports ordinary role grants and revocations, typed Auth<Role> proofs, delayed root-role transfer, delayed root-role renounce, and delayed changes to the root-operation delay. The current root-role holder is exposed as the default admin. Elapsed delay changes are effective for reads and are cleared by the next delay-refreshing scheduling action.
Types
Functions
new(otw, default_admin_delay_ms, ctx)new_with_admin(otw, initial_admin, default_admin_delay_ms, ctx)has_role(ac, account)get_role_admin(ac)assert_has_role(ac, account)grant_role(ac, account, ctx)revoke_role(ac, account, ctx)renounce_role(ac, ctx)set_role_admin(ac, ctx)begin_default_admin_transfer(ac, new_admin, clock, ctx)accept_default_admin_transfer(ac, clock, ctx)begin_default_admin_renounce(ac, clock, ctx)accept_default_admin_renounce(ac, clock, ctx)cancel_default_admin_transfer(ac, ctx)begin_default_admin_delay_change(ac, new_delay_ms, clock, ctx)cancel_default_admin_delay_change(ac, clock, ctx)new_auth(ac, ctx)auth_addr(auth)protected_root(ac)default_admin(ac)max_default_admin_delay_ms()default_admin_delay_ms(ac, clock)has_pending_default_admin_transfer(ac)is_pending_default_admin_renounce(ac)pending_default_admin_new_admin(ac)pending_default_admin_execute_after_ms(ac)max_delay_increase_wait_ms()has_pending_default_admin_delay_change(ac, clock)pending_default_admin_delay_change_new_delay_ms(ac, clock)pending_default_admin_delay_change_schedule_after_ms(ac, clock)
Events
RoleGrantedRoleRevokedRoleAdminChangedDefaultAdminTransferScheduledDefaultAdminRenounceScheduledDefaultAdminTransferCancelledDefaultAdminRenounceCancelledDefaultAdminDelayChangeScheduledDefaultAdminDelayChangeCancelled
Errors
EUnauthorizedECannotManageRootRoleENoPendingAdminTransferENotPendingAdminEDelayNotElapsedEDelayTooLargeENotOneTimeWitnessEForeignRoleENotPendingTransferENotPendingRenounceENoPendingDelayChangeEZeroAddressEDefaultAdminTransferToSelf
Types
struct Auth<Role>
struct
#Drop-only typed proof that the transaction sender held Role when the proof was minted with new_auth.
Because new_auth only mints against the singleton registry for Role's home module, consumers can take &Auth<Role> as authorization without repeating role checks. The proof is a PTB-local snapshot: if the holder later renounces Role in the same PTB, the existing proof remains valid.
struct AccessControl<RootRole>
struct
#Key object storing non-root role membership, role-admin relationships, the current default admin, root-role pending state, pending delay changes, and the current root-operation delay.
RootRole is the consuming module's OTW type. It pins the registry identity and is the protected root role for the registry. The current default admin is the sole root-role holder.
struct RoleData
struct
#Per-role membership and admin-role data.
struct PendingAdminTransfer
struct
#Pending root-role action. new_admin = some(address) means transfer, while new_admin = none means renounce. Transfer and renounce share one pending slot, so scheduling either one cancels and overwrites the other.
struct PendingDelayChange
struct
#Pending change to default_admin_delay_ms, including the new delay and the timestamp after which it becomes effective. Public pending-delay getters report only active, unelapsed changes; the stored slot is cleared later by a delay-refreshing scheduling entrypoint.
Functions
new<RootRole: drop>(otw: RootRole, default_admin_delay_ms: u64, ctx: &mut TxContext) -> AccessControl<RootRole>
public
#Creates the registry for the consumer module. RootRole must be a genuine OTW, and ctx.sender() becomes the initial default admin and root-role holder.
The caller is responsible for sharing, embedding, or otherwise positioning the returned AccessControl<RootRole> registry.
The expected call site is the consumer module's init, which only runs on the package's first publish. To adopt AccessControl from an already-published protocol, publish a new package that initializes its own registry.
Aborts with ENotOneTimeWitness if otw is not an OTW.
Aborts with EDelayTooLarge if default_admin_delay_ms exceeds max_default_admin_delay_ms().
new_with_admin<RootRole: drop>(otw: RootRole, initial_admin: address, default_admin_delay_ms: u64, ctx: &mut TxContext) -> AccessControl<RootRole>
public
#Creates the registry with an explicit initial default admin.
Use this when the initial root-role holder should be a governance or multisig address rather than the publishing transaction sender. Otherwise use new.
Aborts with ENotOneTimeWitness if otw is not an OTW.
Aborts with EDelayTooLarge if default_admin_delay_ms exceeds max_default_admin_delay_ms().
Aborts with EZeroAddress if initial_admin is @0x0.
has_role<RootRole, Role>(ac: &AccessControl<RootRole>, account: address) -> bool
public
#Returns whether account currently holds Role.
Root-role membership is read from the dedicated default-admin field. Non-root roles that have never been registered return false.
get_role_admin<RootRole, Role>(ac: &AccessControl<RootRole>) -> TypeName
public
#Returns the admin role for Role, defaulting to the protected root role when no role data exists yet.
Calling this with Role = RootRole returns the root role's own TypeName.
Aborts with EForeignRole if Role is not defined in the same module as RootRole.
assert_has_role<RootRole, Role>(ac: &AccessControl<RootRole>, account: address)
public
#Checks that account holds Role.
Aborts with EUnauthorized if account does not hold Role.
grant_role<RootRole, Role>(ac: &mut AccessControl<RootRole>, account: address, ctx: &mut TxContext)
public
#Grants Role to account. Caller must hold the admin role of Role. No-op if account already has the role.
Aborts with EForeignRole if Role is not defined in the same module as RootRole.
Aborts with ECannotManageRootRole if Role is the root role.
Aborts with EUnauthorized if caller does not hold the admin role of Role.
Aborts with EZeroAddress if account is @0x0.
revoke_role<RootRole, Role>(ac: &mut AccessControl<RootRole>, account: address, ctx: &mut TxContext)
public
#Revokes Role from account. Caller must hold the admin role of Role. No-op if account does not have the role.
Aborts with EForeignRole if Role is not defined in the same module as RootRole.
Aborts with ECannotManageRootRole if Role is the root role.
Aborts with EUnauthorized if caller does not hold the admin role of Role.
renounce_role<RootRole, Role>(ac: &mut AccessControl<RootRole>, ctx: &mut TxContext)
public
#Lets the caller renounce their own non-root Role. No-op if caller does not hold Role.
Aborts with EForeignRole if Role is not defined in the same module as RootRole.
Aborts with ECannotManageRootRole if Role is the root role. Root renounce must use begin_default_admin_renounce and accept_default_admin_renounce.
set_role_admin<RootRole, Role, AdminRole>(ac: &mut AccessControl<RootRole>, ctx: &mut TxContext)
public
#Changes the admin role for Role to AdminRole. Caller must hold the current admin role of Role.
Aborts with EForeignRole if either Role or AdminRole is not defined in the same module as RootRole.
Aborts with ECannotManageRootRole if Role is the root role.
Aborts with EUnauthorized if caller lacks the current admin role of Role.
begin_default_admin_transfer<RootRole>(ac: &mut AccessControl<RootRole>, new_admin: address, clock: &Clock, ctx: &mut TxContext)
public
#Schedules a root-role transfer to new_admin at clock.timestamp_ms() plus the effective default_admin_delay_ms.
Caller must hold the root role. An existing pending transfer or renounce is cancelled and overwritten. If a pending delay change has elapsed, it is applied before the transfer is scheduled.
Aborts with EUnauthorized if caller does not hold the root role.
Aborts with EZeroAddress if new_admin is @0x0. Use begin_default_admin_renounce to permanently lock the registry.
Aborts with EDefaultAdminTransferToSelf if new_admin is the current root holder.
accept_default_admin_transfer<RootRole>(ac: &mut AccessControl<RootRole>, clock: &Clock, ctx: &mut TxContext)
public
#Accepts a pending root-role transfer after the scheduled delay. Caller must be the pending new admin.
The call clears the pending action, revokes the old root holder, and grants the root role to the caller.
Aborts with ENoPendingAdminTransfer if there is no pending transfer or renounce.
Aborts with ENotPendingTransfer if the pending action is a renounce.
Aborts with ENotPendingAdmin if caller is not the scheduled new admin.
Aborts with EDelayNotElapsed if the timelock has not elapsed.
begin_default_admin_renounce<RootRole>(ac: &mut AccessControl<RootRole>, clock: &Clock, ctx: &mut TxContext)
public
#Schedules a root-role renounce at clock.timestamp_ms() plus the effective default_admin_delay_ms.
Caller must hold the root role. An existing pending transfer or renounce is cancelled and overwritten. If a pending delay change has elapsed, it is applied before the renounce is scheduled.
Aborts with EUnauthorized if caller does not hold the root role.
accept_default_admin_renounce<RootRole>(ac: &mut AccessControl<RootRole>, clock: &Clock, ctx: &mut TxContext)
public
#Finalizes a pending root-role renounce after the scheduled delay. Caller must still hold the root role.
After this call, no account holds the root role and root administration is permanently unavailable unless another protocol-specific recovery path exists.
Aborts with ENoPendingAdminTransfer if there is no pending transfer or renounce.
Aborts with ENotPendingRenounce if the pending action is a transfer.
Aborts with EUnauthorized if caller does not hold the root role.
Aborts with EDelayNotElapsed if the timelock has not elapsed.
cancel_default_admin_transfer<RootRole>(ac: &mut AccessControl<RootRole>, ctx: &mut TxContext)
public
#Cancels a pending root-role transfer or pending root-role renounce. Caller must hold the root role.
Emits DefaultAdminTransferCancelled for a transfer, or DefaultAdminRenounceCancelled for a renounce.
Aborts with ENoPendingAdminTransfer if there is no pending transfer or renounce.
Aborts with EUnauthorized if caller does not hold the root role.
begin_default_admin_delay_change<RootRole>(ac: &mut AccessControl<RootRole>, new_delay_ms: u64, clock: &Clock, ctx: &mut TxContext)
public
#Schedules a change to default_admin_delay_ms. Caller must hold the root role, and new_delay_ms must not exceed max_default_admin_delay_ms().
Increases wait for min(new_delay_ms, max_delay_increase_wait_ms()); decreases wait for current_delay_ms - new_delay_ms; no change waits 0.
If an existing pending delay change has elapsed, it is applied first. If an existing pending delay change has not elapsed, it is cancelled and overwritten.
Aborts with EUnauthorized if caller does not hold the root role.
Aborts with EDelayTooLarge if new_delay_ms exceeds max_default_admin_delay_ms().
cancel_default_admin_delay_change<RootRole>(ac: &mut AccessControl<RootRole>, clock: &Clock, ctx: &mut TxContext)
public
#Cancels an unelapsed pending delay change. Caller must hold the root role.
If the pending delay change has already elapsed, the change is effective and no longer cancellable; this call aborts with ENoPendingDelayChange.
Aborts with ENoPendingDelayChange if no active pending delay change exists.
Aborts with EUnauthorized if caller does not hold the root role.
new_auth<RootRole, Role>(ac: &AccessControl<RootRole>, ctx: &mut TxContext) -> Auth<Role>
public
#Mints a temporary Auth<Role> proof for ctx.sender(). Pass it by reference to gated functions in the same PTB.
The proof shows membership at mint time. If the holder later renounces Role in the same PTB, the already minted proof still authorizes later calls in that PTB.
Aborts with EForeignRole if Role is not defined in the same module as RootRole.
Aborts with EUnauthorized if sender does not hold Role.
auth_addr<Role>(auth: &Auth<Role>) -> address
public
#Returns the address that held Role when auth was minted.
protected_root<RootRole>(ac: &AccessControl<RootRole>) -> TypeName
public
#Returns the TypeName of the protected root role captured at construction time.
default_admin<RootRole>(ac: &AccessControl<RootRole>) -> Option<address>
public
#Returns the current default admin, or none if the root role has been renounced.
The default admin is the sole current root-role holder.
max_default_admin_delay_ms() -> u64
public
#Returns the maximum allowed root-operation delay: 60 days in milliseconds.
default_admin_delay_ms<RootRole>(ac: &AccessControl<RootRole>, clock: &Clock) -> u64
public
#Returns the effective delay, in milliseconds, for root transfers and root renounces.
If a pending delay change has elapsed, this returns the pending new delay even if the stored pending slot has not been cleared yet.
has_pending_default_admin_transfer<RootRole>(ac: &AccessControl<RootRole>) -> bool
public
#Returns whether there is any pending root-role action: either a transfer or a renounce.
is_pending_default_admin_renounce<RootRole>(ac: &AccessControl<RootRole>) -> bool
public
#Returns whether the pending root-role action is specifically a renounce. Returns false when there is no pending action or when the pending action is a transfer.
pending_default_admin_new_admin<RootRole>(ac: &AccessControl<RootRole>) -> Option<address>
public
#Returns some(address) for a pending transfer. Returns none when there is no pending action or when the pending action is a renounce.
Use is_pending_default_admin_renounce to distinguish no pending action from pending renounce.
pending_default_admin_execute_after_ms<RootRole>(ac: &AccessControl<RootRole>) -> Option<u64>
public
#Returns some(timestamp_ms) with the timestamp after which the pending root-role action can be accepted. Returns none when no root action is pending.
max_delay_increase_wait_ms() -> u64
public
#Returns the maximum wait before a scheduled delay increase can take effect: 48 hours in milliseconds.
has_pending_default_admin_delay_change<RootRole>(ac: &AccessControl<RootRole>, clock: &Clock) -> bool
public
#Returns whether a default-admin delay change is active and cancellable.
Returns false once clock.timestamp_ms() reaches the scheduled timestamp, because the change is then effective and no longer cancellable.
pending_default_admin_delay_change_new_delay_ms<RootRole>(ac: &AccessControl<RootRole>, clock: &Clock) -> Option<u64>
public
#Returns some(new_delay_ms) with the proposed delay if a change is active and cancellable. Returns none otherwise.
Returns none once clock.timestamp_ms() reaches the scheduled timestamp.
pending_default_admin_delay_change_schedule_after_ms<RootRole>(ac: &AccessControl<RootRole>, clock: &Clock) -> Option<u64>
public
#Returns some(timestamp_ms) with the timestamp after which an active pending delay change becomes effective. Returns none otherwise.
Returns none once clock.timestamp_ms() reaches that timestamp.
Events
Access-control events are generic over RootRole, so the event type identifies the registry's root module. The Sui event envelope carries the transaction sender; event payloads do not duplicate it.
RoleGranted<RootRole>(role: TypeName, account: address)
event
#Emitted when a role is granted to an account.
Fired by grant_role when account was not already a member, by new or new_with_admin for the initial root holder, and by accept_default_admin_transfer for the incoming root holder.
The role field is a TypeName that identifies the defining package address and module of the role struct.
RoleRevoked<RootRole>(role: TypeName, account: address)
event
#Emitted when a role is removed from an account.
Fired by revoke_role when account held the role, by renounce_role, by accept_default_admin_transfer for the previous root holder, and by accept_default_admin_renounce for the renouncing root holder.
The role field is a TypeName that identifies the defining package address and module of the role struct.
RoleAdminChanged<RootRole>(role: TypeName, previous_admin_role: TypeName, new_admin_role: TypeName)
event
#Emitted when a role's admin role is reconfigured by set_role_admin.
The role, previous_admin_role, and new_admin_role fields are TypeNames.
DefaultAdminTransferScheduled<RootRole>(new_admin: address, execute_after_ms: u64)
event
#Emitted when a root-role transfer is scheduled by begin_default_admin_transfer.
execute_after_ms is the earliest timestamp at which accept_default_admin_transfer can be called.
DefaultAdminRenounceScheduled<RootRole>(execute_after_ms: u64)
event
#Emitted when a root-role renounce is scheduled by begin_default_admin_renounce.
execute_after_ms is the earliest timestamp at which accept_default_admin_renounce can be called.
DefaultAdminTransferCancelled<RootRole>()
event
#Emitted when a pending root-role transfer is cancelled, either by cancel_default_admin_transfer or because a new pending root action overwrites it.
Indexers can correlate this event with the prior DefaultAdminTransferScheduled event.
DefaultAdminRenounceCancelled<RootRole>()
event
#Emitted when a pending root-role renounce is cancelled, either by cancel_default_admin_transfer or because a new pending root action overwrites it.
Indexers can correlate this event with the prior DefaultAdminRenounceScheduled event.
DefaultAdminDelayChangeScheduled<RootRole>(new_delay_ms: u64, schedule_after_ms: u64)
event
#Emitted when a default-admin delay change is scheduled by begin_default_admin_delay_change.
new_delay_ms is the proposed new delay. schedule_after_ms is the timestamp at which it becomes effective.
DefaultAdminDelayChangeCancelled<RootRole>()
event
#Emitted when an unelapsed pending default-admin delay change is cancelled, either by cancel_default_admin_delay_change or because a new pending delay change overwrites it.
Errors
ECannotManageRootRole
error
#Raised when grant, revoke, renounce, or admin-change logic is used on the root role instead of the delayed root flows.
ENoPendingAdminTransfer
error
#Raised when accept_default_admin_transfer, accept_default_admin_renounce, or cancel_default_admin_transfer expects a pending root transfer or renounce but none exists.
ENotPendingAdmin
error
#Raised when a caller other than the scheduled new root holder tries to accept a root transfer.
EDelayNotElapsed
error
#Raised when accept_default_admin_transfer or accept_default_admin_renounce is called before the pending action's timelock has elapsed.
EDelayTooLarge
error
#Raised when the initial or scheduled default-admin delay exceeds max_default_admin_delay_ms().
ENotOneTimeWitness
error
#Raised when new or new_with_admin receives a value that is not a genuine OTW.
EForeignRole
error
#Raised when a role-typed path that enforces the home-module rule uses a role type from a module other than the root role's home module.
ENotPendingTransfer
error
#Raised when accept_default_admin_transfer is called while the pending root action is a renounce.
ENotPendingRenounce
error
#Raised when accept_default_admin_renounce is called while the pending root action is a transfer.
ENoPendingDelayChange
error
#Raised when cancelling a default-admin delay change but no active, unelapsed delay change is pending.
EZeroAddress
error
#Raised when new_with_admin, grant_role, or begin_default_admin_transfer is called with @0x0 as the target address.
The zero address has no signing key, so a role granted to it can never be exercised and a root transfer scheduled to it can never be accepted.
EDefaultAdminTransferToSelf
error
#Raised when the current root holder schedules a root transfer to itself.
use openzeppelin_access::two_step_transfer;Two-step ownership wrapper for T: key + store objects. Transfers require explicit initiation and acceptance, with cancellation authority bound to the recorded initiator (ctx.sender() at initiation time).
This module is designed for flows with a single logical owner. Avoid using it directly in shared-object custody flows where arbitrary executors can trigger initiate_transfer, because the initiator becomes the recorded cancel authority.
Types
Functions
wrap(obj, ctx)borrow(self)borrow_mut(self)borrow_val(self)return_val(self, obj, borrow)unwrap(self, ctx)initiate_transfer(self, new_owner, ctx)accept_transfer(request, wrapper_ticket, ctx)cancel_transfer(request, wrapper_ticket, ctx)request_borrow_val(request, wrapper_ticket, ctx)request_return_val(request, wrapper, borrow)
Events
Errors
EInvalidTransferRequestEWrongTwoStepTransferWrapperEWrongTwoStepTransferObjectENotOwnerENotNewOwner
Types
struct WrappedKey()
struct
#Dynamic object-field key used to store the wrapped object under the wrapper.
struct TwoStepTransferWrapper<T: key + store>
struct
#Wrapper object that custody-locks an underlying object and controls transfer flow.
The wrapper intentionally omits store so transfer paths stay constrained to this module's logic.
struct PendingOwnershipTransfer<T: key + store>
struct
#Shared pending-transfer object storing wrapper identity, current owner (from), and prospective owner (to).
Wrapper custody is held by this request object through transfer-to-object (TTO) until accept/cancel resolution.
struct Borrow
struct
#Hot-potato guard proving that a value taken via borrow_val is returned to the same wrapper.
struct RequestBorrow
struct
#Hot-potato guard proving a wrapper borrowed through a pending request is returned to that request.
Functions
wrap<T: key + store>(obj: T, ctx: &mut TxContext) -> TwoStepTransferWrapper<T>
public
#Wraps obj in a new transfer wrapper.
The wrapped object is stored as a dynamic object field so off-chain indexers can still discover the underlying object ID.
Emits a WrapExecuted event.
borrow<T: key + store>(self: &TwoStepTransferWrapper<T>) -> &T
public
#Returns immutable access to the wrapped object.
borrow_mut<T: key + store>(self: &mut TwoStepTransferWrapper<T>) -> &mut T
public
#Returns mutable access to the wrapped object without changing ownership state.
borrow_val<T: key + store>(self: &mut TwoStepTransferWrapper<T>) -> (T, Borrow)
public
#Temporarily extracts the wrapped object and returns a Borrow guard that must be consumed by return_val.
return_val<T: key + store>(self: &mut TwoStepTransferWrapper<T>, obj: T, borrow: Borrow)
public
#Returns a previously borrowed object to the wrapper.
Aborts when wrapper/object identity checks fail.
unwrap<T: key + store>(self: TwoStepTransferWrapper<T>, ctx: &mut TxContext) -> T
public
#Destroys the wrapper and returns the underlying object directly to the caller.
This bypasses pending-request flow and recovers direct ownership of the wrapped object.
Emits an UnwrapExecuted event.
initiate_transfer<T: key + store>(self: TwoStepTransferWrapper<T>, new_owner: address, ctx: &mut TxContext)
public
#Starts a transfer by creating a shared request and transferring wrapper custody to that request.
Security note: cancellation authority is tied to the initiating signer recorded as from.
Only use this flow when the signer executing initiation is intentionally the logical owner/cancel authority.
Emits a TransferInitiated event.
accept_transfer<T: key + store>(request: PendingOwnershipTransfer<T>, wrapper_ticket: Receiving<TwoStepTransferWrapper<T>>, ctx: &mut TxContext)
public
#Completes a pending transfer and sends the wrapper to the designated new owner.
Aborts if caller is not request.to or wrapper identity does not match.
Emits a TransferAccepted event.
cancel_transfer<T: key + store>(request: PendingOwnershipTransfer<T>, wrapper_ticket: Receiving<TwoStepTransferWrapper<T>>, ctx: &mut TxContext)
public
#Cancels a pending transfer and returns the wrapper to request.from.
Aborts if caller is not request.from or wrapper identity does not match.
Emits a TransferCancelled event.
request_borrow_val<T: key + store>(request: &mut PendingOwnershipTransfer<T>, wrapper_ticket: Receiving<TwoStepTransferWrapper<T>>, ctx: &mut TxContext) -> (TwoStepTransferWrapper<T>, RequestBorrow)
public
#Receives wrapper custody from a shared request so the recorded owner can operate on the wrapped object during a pending transfer.
Aborts if caller is not request.from or if request/wrapper identity checks fail.
request_return_val<T: key + store>(request: &PendingOwnershipTransfer<T>, wrapper: TwoStepTransferWrapper<T>, borrow: RequestBorrow)
public
#Returns a wrapper borrowed via request_borrow_val back to the pending request.
Aborts if either wrapper or borrow does not match the target request.
Events
WrapExecuted<T>(wrapper_id: ID, object_id: ID, owner: address)
event
#Emitted when an object is wrapped.
UnwrapExecuted<T>(wrapper_id: ID, object_id: ID, owner: address)
event
#Emitted when an object is unwrapped.
TransferInitiated<T>(wrapper_id: ID, current_owner: address, new_owner: address)
event
#Emitted when a two-step transfer request is created.
TransferAccepted<T>(wrapper_id: ID, previous_owner: address, new_owner: address)
event
#Emitted when a pending transfer is accepted and ownership moves to the new owner.
TransferCancelled<T>(wrapper_id: ID, current_owner: address, new_owner: address)
event
#Emitted when a pending transfer is cancelled.
Errors
EInvalidTransferRequest
error
#Raised when request and wrapper identities do not match.
EWrongTwoStepTransferWrapper
error
#Raised when a Borrow guard is used against a different wrapper.
EWrongTwoStepTransferObject
error
#Raised when returning an object different from the one originally borrowed.
ENotOwner
error
#Raised when caller is not authorized as the current owner for the requested operation.
ENotNewOwner
error
#Raised when caller is not the designated prospective owner in accept_transfer.
use openzeppelin_access::delayed_transfer;Time-locked ownership wrapper for T: key + store. The wrapped object is placed under a wrapper that is immediately transferred to a chosen recipient. After that, transfers and unwraps must be scheduled and can only execute after min_delay_ms elapses.
Types
Functions
wrap(obj, min_delay_ms, recipient, ctx)borrow(self)borrow_mut(self)borrow_val(self)return_val(self, obj, borrow)schedule_transfer(self, new_owner, clock, ctx)schedule_unwrap(self, clock, ctx)execute_transfer(self, clock, ctx)unwrap(self, clock, ctx)cancel_schedule(self)
Events
WrapExecutedTransferScheduledUnwrapScheduledOwnershipTransferredPendingTransferCancelledUnwrapExecuted
Errors
ETransferAlreadyScheduledENoPendingTransferEDelayNotElapsedEWrongPendingActionEWrongDelayedTransferWrapperEWrongDelayedTransferObject
Types
struct WrappedKey()
struct
#Dynamic object-field key used to store the wrapped object under the wrapper.
struct DelayedTransferWrapper<T: key + store>
struct
#Wrapper object storing min_delay_ms and optional pending schedule state.
struct PendingTransfer { recipient: Option<address>, execute_after_ms: u64 }
struct
#Represents a scheduled transfer (recipient = some) or scheduled unwrap (recipient = none).
struct Borrow
struct
#Hot-potato guard proving a value extracted with borrow_val is returned to the same wrapper.
Functions
wrap<T: key + store>(obj: T, min_delay_ms: u64, recipient: address, ctx: &mut TxContext)
public
#Wraps obj in a delayed-transfer wrapper, records the minimum execution delay, and transfers initial wrapper custody to recipient.
The wrapped object is stored under a dynamic object field so object ID discovery remains straightforward for indexers.
Emits a WrapExecuted event.
borrow<T: key + store>(self: &DelayedTransferWrapper<T>) -> &T
public
#Returns immutable access to the wrapped object.
borrow_mut<T: key + store>(self: &mut DelayedTransferWrapper<T>) -> &mut T
public
#Returns mutable access to the wrapped object.
borrow_val<T: key + store>(self: &mut DelayedTransferWrapper<T>) -> (T, Borrow)
public
#Temporarily extracts the wrapped object and returns a guard that must be consumed by return_val.
return_val<T: key + store>(self: &mut DelayedTransferWrapper<T>, obj: T, borrow: Borrow)
public
#Returns a previously borrowed object to its wrapper.
Aborts when wrapper/object identity checks fail.
schedule_transfer<T: key + store>(self: &mut DelayedTransferWrapper<T>, new_owner: address, clock: &Clock, ctx: &mut TxContext)
public
#Schedules a transfer to new_owner at clock.timestamp_ms() + min_delay_ms.
Aborts when another action is already scheduled.
Emits a TransferScheduled event.
schedule_unwrap<T: key + store>(self: &mut DelayedTransferWrapper<T>, clock: &Clock, ctx: &mut TxContext)
public
#Schedules delayed self-recovery (unwrap) of the wrapped object.
Aborts when another action is already scheduled.
Emits an UnwrapScheduled event.
execute_transfer<T: key + store>(self: DelayedTransferWrapper<T>, clock: &Clock, ctx: &mut TxContext)
public
#Executes a scheduled transfer once delay has elapsed.
Consumes the wrapper.
Aborts when no transfer is scheduled, wrong action type is scheduled, or delay has not elapsed.
Emits an OwnershipTransferred event on success.
unwrap<T: key + store>(self: DelayedTransferWrapper<T>, clock: &Clock, ctx: &mut TxContext) -> T
public
#Executes a scheduled unwrap once delay has elapsed and returns the wrapped object.
Aborts when no unwrap is scheduled, wrong action type is scheduled, or delay has not elapsed.
Emits an UnwrapExecuted event.
cancel_schedule<T: key + store>(self: &mut DelayedTransferWrapper<T>)
public
#Cancels the currently scheduled transfer or unwrap action.
Aborts when no action is pending.
Emits a PendingTransferCancelled event.
Events
WrapExecuted<T>(wrapper_id: ID, object_id: ID, owner: address)
event
#Emitted when an object is wrapped.
TransferScheduled<T>(wrapper_id: ID, current_owner: address, new_owner: address, execute_after_ms: u64)
event
#Emitted when a delayed transfer is scheduled.
UnwrapScheduled<T>(wrapper_id: ID, current_owner: address, execute_after_ms: u64)
event
#Emitted when delayed unwrap is scheduled.
OwnershipTransferred<T>(wrapper_id: ID, previous_owner: address, new_owner: address)
event
#Emitted when scheduled transfer execution completes.
PendingTransferCancelled<T>(wrapper_id: ID)
event
#Emitted when pending schedule is cancelled.
UnwrapExecuted<T>(wrapper_id: ID, object_id: ID, owner: address)
event
#Emitted when delayed unwrap execution completes.
Errors
ETransferAlreadyScheduled
error
#Raised when trying to schedule while another action is already pending.
ENoPendingTransfer
error
#Raised when execution/cancellation is requested without pending state.
EDelayNotElapsed
error
#Raised when execution occurs before execute_after_ms.
EWrongPendingAction
error
#Raised when calling transfer execution on unwrap state (or vice versa).
EWrongDelayedTransferWrapper
error
#Raised when a Borrow guard is used against a different wrapper.
EWrongDelayedTransferObject
error
#Raised when returning an object different from the one originally borrowed.