Skip to main content

PausableCancellable

The PausableCancellable is an abstract utility contract that provides pause and cancel functionality for emergency controls and state management in campaigns and treasuries.

Overview​

abstract contract PausableCancellable {
    bool private _paused;
    bool private _cancelled;
    
    event Paused(address indexed account, bytes32 reason);
    event Unpaused(address indexed account, bytes32 reason);
    event Cancelled(address indexed account, bytes32 reason);
    
    modifier whenNotPaused();
    modifier whenPaused();
    modifier whenNotCancelled();
    modifier whenCancelled();
    
    function paused() public view virtual returns (bool);
    function cancelled() public view virtual returns (bool);
    function _pause(bytes32 reason) internal virtual;
    function _unpause(bytes32 reason) internal virtual;
    function _cancel(bytes32 reason) internal virtual;
}

Purpose​

  • Emergency Controls: Allow pausing campaigns in emergencies
  • Cancellation Support: Permanent cancellation capability
  • State Management: Track paused and cancelled states
  • Reusable: Can be inherited by any contract needing these states
  • Safe Defaults: Prevents operations when paused/cancelled

State Variables​

VariableTypeDescription
_pausedboolWhether contract is paused
_cancelledboolWhether contract is cancelled

Functions​

State Queries​

Paused​

function paused() public view virtual returns (bool);

Returns:

  • True if contract is paused

Cancelled​

function cancelled() public view virtual returns (bool);

Returns:

  • True if contract is cancelled

State Management​

Pause​

function _pause(bytes32 reason) internal virtual;

Parameters:

  • reason: Reason for pausing

Effects:

  • Sets _paused to true
  • Emits Paused event
  • Stops most operations

Requirements:

  • Contract must not be paused
  • Contract must not be cancelled

Unpause​

function _unpause(bytes32 reason) internal virtual;

Parameters:

  • reason: Reason for unpausing

Effects:

  • Sets _paused to false
  • Emits Unpaused event
  • Resumes operations

Requirements:

  • Contract must be paused

Cancel​

function _cancel(bytes32 reason) internal virtual;

Parameters:

  • reason: Reason for cancellation

Effects:

  • Sets _cancelled to true
  • Unpauses if paused
  • Emits Cancelled event
  • Prevents future operations

Requirements:

  • Contract must not be cancelled
  • Cancellation is permanent and irreversible

Modifiers​

When Not Paused​

modifier whenNotPaused();

Effect:

  • Reverts if contract is paused
  • Used on functions that should be disabled when paused

When Paused​

modifier whenPaused();

Effect:

  • Reverts if contract is not paused
  • Used on functions that should only work when paused

When Not Cancelled​

modifier whenNotCancelled();

Effect:

  • Reverts if contract is cancelled
  • Used on most functions to prevent operations

When Cancelled​

modifier whenCancelled();

Effect:

  • Reverts if contract is not cancelled
  • Used on functions that should only work when cancelled

Events​

Paused​

event Paused(address indexed account, bytes32 reason);

Emitted when: Contract is paused Includes: Account that paused, reason for pausing

Unpaused​

event Unpaused(address indexed account, bytes32 reason);

Emitted when: Contract is unpaused Includes: Account that unpaused, reason

Cancelled​

event Cancelled(address indexed account, bytes32 reason);

Emitted when: Contract is cancelled Includes: Account that cancelled, reason

Errors​

PausedError​

error PausedError();

Thrown when: Operation attempted while paused

NotPausedError​

error NotPausedError();

Thrown when: Unpause attempted when not paused

CancelledError​

error CancelledError();

Thrown when: Operation attempted when cancelled

CannotCancel​

error CannotCancel();

Thrown when: Cancel attempted on already-cancelled contract

Usage Examples​

Using State Modifiers​

contract MyContract is PausableCancellable {
    // Only works when not paused/cancelled
    function normalFunction() external whenNotPaused whenNotCancelled {
        // Implementation
    }
    
    // Only works when paused
    function emergencyFunction() external whenPaused {
        // Implementation
    }
    
    // Only works when cancelled
    function cleanupFunction() external whenCancelled {
        // Implementation
    }
}

Checking State​

// Check if campaign is paused
const isPaused = await campaign.paused();
if (isPaused) {
  console.log('Campaign is paused');
}

// Check if campaign is cancelled
const isCancelled = await campaign.cancelled();
if (isCancelled) {
  console.log('Campaign is cancelled');
}

// Only proceed if active
if (!isPaused && !isCancelled) {
  await treasury.pledge(amount);
}

Emergency Pause​

// Protocol admin pauses campaign
const reason = ethers.utils.keccak256(ethers.utils.toUtf8Bytes('security-issue'));
await campaign._pauseCampaign(reason);

// All operations now fail
try {
  await treasury.pledge(amount);
} catch (error) {
  console.log('Campaign is paused');
}

// Unpause when issue resolved
const unpauseReason = ethers.utils.keccak256(
  ethers.utils.toUtf8Bytes('issue-resolved')
);
await campaign._unpauseCampaign(unpauseReason);

Cancellation​

// Cancel campaign permanently
const reason = ethers.utils.keccak256(ethers.utils.toUtf8Bytes('owner-request'));
await campaign._cancelCampaign(reason);

// All operations now fail
try {
  await treasury.pledge(amount);
} catch (error) {
  console.log('Campaign is cancelled');
}

// Cancellation cannot be reversed
// Campaign is permanently ended

Integration​

With CampaignInfo​

contract CampaignInfo is PausableCancellable {
    function _pauseCampaign(bytes32 message) 
        external 
        onlyProtocolAdmin 
    {
        _pause(message);
    }
    
    function _unpauseCampaign(bytes32 message) 
        external 
        onlyProtocolAdmin 
    {
        _unpause(message);
    }
    
    function _cancelCampaign(bytes32 message) 
        external 
    {
        // Only owner or protocol admin
        _cancel(message);
    }
}

With BaseTreasury​

abstract contract BaseTreasury is PausableCancellable {
    modifier whenCampaignNotPaused() {
        _revertIfCampaignPaused();
        _;
    }
    
    modifier whenCampaignNotCancelled() {
        _revertIfCampaignCancelled();
        _;
    }
    
    function pledge() external whenNotPaused whenNotCancelled {
        // Only works when active
    }
}

State Transitions​

Paused​

Active → Paused (via _pause)
Paused → Active (via _unpause)
Paused → Cancelled (via _cancel, auto-unpauses)

Cancelled​

Active → Cancelled (via _cancel)
Paused → Cancelled (via _cancel, auto-unpauses)
Cancelled → [No transitions possible - permanent]

Security Considerations​

Permanent Cancellation​

  • Cancellation is irreversible
  • No way to recover from cancelled state
  • All operations permanently disabled
  • Use only when absolutely necessary

Pause vs Cancel​

  • Pause: Temporary, can be unpaused
  • Cancel: Permanent, cannot be undone
  • Choose carefully which to use

Access Control​

  • Only authorized accounts can pause/unpause/cancel
  • Typically protocol admins can pause
  • Campaign owners or protocol admins can cancel

Best Practices​

Use Clear Reasons​

const pauseReason = ethers.utils.keccak256(
  ethers.utils.toUtf8Bytes('exploit-detected-dec-2024')
);

await campaign._pauseCampaign(pauseReason);

// Log reason off-chain for audit trail
await database.logPause(reason, timestamp);

Monitor State Changes​

campaign.on('Paused', (account, reason, event) => {
  console.log('Campaign paused by:', account);
  console.log('Reason:', ethers.utils.toUtf8String(reason));
  
  // Send alert
  sendAlertToUsers('Campaign paused due to emergency');
});

campaign.on('Cancelled', (account, reason, event) => {
  console.log('Campaign cancelled by:', account);
  
  // Update database
  await database.markCampaignCancelled(campaignAddress);
});

Frontend State Checks​

// Always check state before operations
const isPaused = await campaign.paused();
const isCancelled = await campaign.cancelled();

if (isPaused || isCancelled) {
  showMessage('Campaign is not accepting contributions');
  disableInteraction();
  return;
}

// Proceed with operation
await treasury.pledge(amount);

Next Steps​