Icon LinkOwnership Library

The Ownership Library provides a straightforward way to restrict specific calls in a Sway contract to a single owner. Its design follows the SRC-5 Icon Link standard from Sway Standards Icon Link and offers a set of functions to initialize, verify, revoke, and transfer ownership.

For implementation details, visit the Sway Libs Docs Icon Link.

Icon LinkImporting the Ownership Library

1. Add Sway Libs to Forc.toml
   Please see the Getting Started guide for instructions on adding Sway Libs as a dependency.

2. Add Sway Standards to Forc.toml
   Refer to the Sway Standards Book Icon Link to add Sway Standards.

3. Import the Ownership Library
   To import the Ownership Library and the SRC-5 Icon Link standard, include the following in your Sway file:

   use sway_libs::ownership::*;
   use standards::src5::*;

   Icon ClipboardText

Icon LinkIntegrating the Ownership Library into the SRC-5 Standard

When integrating the Ownership Library with SRC-5 Icon Link, ensure that the SRC5 trait from Sway Standards is implemented in your contract, as shown below. The _owner() function from this library is used to fulfill the SRC-5 requirement of exposing the ownership state.

use sway_libs::ownership::_owner;
use standards::src5::{SRC5, State};
 
impl SRC5 for Contract {
    #[storage(read)]
    fn owner() -> State {
        _owner()
    }
}

Icon LinkBasic Usage

Icon LinkSetting a Contract Owner

Establishes the initial ownership state by calling initialize_ownership(new_owner). This can only be done once, typically in your contract's constructor.

#[storage(read, write)]
fn my_constructor(new_owner: Identity) {
    initialize_ownership(new_owner);
}

Icon LinkApplying Restrictions

Protect functions so only the owner can call them by invoking only_owner() at the start of those functions.

#[storage(read)]
fn only_owner_may_call() {
    only_owner();
    // Only the contract's owner may reach this line.
}

Icon LinkChecking the Ownership Status

To retrieve the current ownership state, call _owner().

#[storage(read)]
fn get_owner_state() {
    let owner: State = _owner();
}

Icon LinkTransferring Ownership

To transfer ownership from the current owner to a new owner, call transfer_ownership(new_owner).

#[storage(read, write)]
fn transfer_contract_ownership(new_owner: Identity) {
    // The caller must be the current owner.
    transfer_ownership(new_owner);
}

Icon LinkRenouncing Ownership

To revoke ownership entirely and disallow the assignment of a new owner, call renounce_ownership().

#[storage(read, write)]
fn renounce_contract_owner() {
    // The caller must be the current owner.
    renounce_ownership();
    // Now no one owns the contract.
}

Icon LinkEvents

Icon LinkOwnershipRenounced

Emitted when ownership is revoked.

• Fields:
  • previous_owner: Identity of the owner prior to revocation.

Icon LinkOwnershipSet

Emitted when initial ownership is set.

• Fields:
  • new_owner: Identity of the newly set owner.

Icon LinkOwnershipTransferred

Emitted when ownership is transferred from one owner to another.

• Fields:
  • new_owner: Identity of the new owner.
  • previous_owner: Identity of the prior owner.

Icon LinkErrors

Icon LinkInitializationError

• Variants:
  • CannotReinitialized: Thrown when attempting to initialize ownership if the owner is already set.

Icon LinkAccessError

• Variants:
  • NotOwner: Thrown when a function restricted to the owner is called by a non-owner.

Icon LinkExample Integration

Below is a example illustrating how to use this library within a Sway contract:

contract;
 
use sway_libs::ownership::{
    _owner,
    initialize_ownership,
    only_owner,
    renounce_ownership,
    transfer_ownership,
};
use standards::src5::{SRC5, State};
 
impl SRC5 for Contract {
    #[storage(read)]
    fn owner() -> State {
        _owner()
    }
}
 
abi MyContract {
    #[storage(read, write)]
    fn constructor(new_owner: Identity);
    #[storage(read)]
    fn restricted_action();
    #[storage(read, write)]
    fn change_owner(new_owner: Identity);
    #[storage(read, write)]
    fn revoke_ownership();
    #[storage(read)]
    fn get_current_owner() -> State;
}
 
impl MyContract for Contract {
    #[storage(read, write)]
    fn constructor(new_owner: Identity) {
        initialize_ownership(new_owner);
    }
 
    // A function restricted to the owner
    #[storage(read)]
    fn restricted_action() {
        only_owner();
        // Protected action
    }
 
    // Transfer ownership
    #[storage(read, write)]
    fn change_owner(new_owner: Identity) {
        transfer_ownership(new_owner);
    }
 
    // Renounce ownership
    #[storage(read, write)]
    fn revoke_ownership() {
        renounce_ownership();
    }
 
    // Get current owner state
    #[storage(read)]
    fn get_current_owner() -> State {
        _owner()
    }
}

1. Initialization: Call constructor(new_owner) once to set the initial owner.
2. Restricted Calls: Use only_owner() to guard any owner-specific functions.
3. Ownership Checks: Retrieve the current owner state via _owner().
4. Transfer or Renounce: Use transfer_ownership(new_owner) or renounce_ownership() for ownership modifications.