Smart Account Policies

Smart Accounts provide flexible security and control through various policy mechanisms. This guide explains the key policies and how to use them effectively.

​

Policies

• Admin Control
• Signer Permissions
• Threshold Management
• Spending Limits
• Time Locks

​

Admin Control

Admin control is an optional security feature that restricts who can modify Smart Account settings. By default (without an admin), any transaction that meets the account’s threshold requirements can modify settings.

When an admin address is set, only that address can modify the account’s configuration. The admin can also remove itself, returning the account to threshold-based control.

​

Setting up Admin Control

You can optionally set an admin address when creating a Smart Account:

POST /api/v1/smart-accounts
{
  "smart_account_signers": [...],
  "threshold": 2,
  "admin_address": "ADMIN_ADDRESS"  // Optional
}

​

Using Admin Control

​

With Admin Set

When an admin address is set:

• Only the admin can modify account settings
• Changes must be made using admin mode
• Regular transactions still follow normal threshold rules

Example admin mode update:

PATCH /api/v1/smart-accounts/{address}?admin=true
{
  "smart_account_signers": [...],
  "threshold": 2,
  "time_lock": 24,
  "transaction_signers": ["ADMIN_ADDRESS"]
}

​

Without Admin (Default)

When no admin is set:

• Any transaction meeting the threshold can modify settings
• No special mode is required
• Changes follow standard multisig rules

Example threshold-based update:

PATCH /api/v1/smart-accounts/{address}
{
  "smart_account_signers": [...],
  "threshold": 2,
  "time_lock": 24,
  "transaction_signers": ["SIGNER1", "SIGNER2"]  // Must meet threshold
}

Important notes:

• Admin control is optional - by default, threshold rules apply to all changes
• When set, only the admin address can modify configuration
• Admin mode requires the admin=true query parameter
• The admin can remove itself by setting admin_address to null
• Regular transactions still follow normal signing rules regardless of admin setting

​

Signer Permissions

Smart Account signers can have different permissions that control what actions they can perform:

​

Permission Types

1. CAN_INITIATE

   • Required to propose new transactions
   • At least one signer must have this permission
   • Typically given to automated services or primary users

2. CAN_VOTE

   • Required to approve transactions
   • Number of CAN_VOTE signers must be sufficient for threshold
   • Used by signers who participate in transaction approval

3. CAN_EXECUTE

   • Required to execute approved transactions
   • At least one signer should have this permission
   • Often given to automated services for transaction finalization

​

Example Configuration

{
  "smart_account_signers": [
    {
      "address": "signer1...",
      "permissions": ["CAN_INITIATE", "CAN_VOTE", "CAN_EXECUTE"]
    },
    {
      "address": "signer2...",
      "permissions": ["CAN_VOTE"]
    },
    {
      "address": "signer3...",
      "permissions": ["CAN_VOTE", "CAN_EXECUTE"]
    }
  ]
}

​

Threshold Management

The threshold defines how many signers must approve a transaction. This creates a flexible M-of-N multisig setup.

​

Threshold Rules

1. Threshold must be greater than 0
2. Threshold cannot exceed the number of signers with CAN_VOTE permission
3. Changes to threshold require meeting the current threshold requirements or using admin mode

​

Example Configurations

2-of-3 Configuration:

{
  "smart_account_signers": [
    {
      "address": "signer1...",
      "permissions": ["CAN_INITIATE", "CAN_VOTE", "CAN_EXECUTE"]
    },
    {
      "address": "signer2...",
      "permissions": ["CAN_VOTE"]
    },
    {
      "address": "signer3...",
      "permissions": ["CAN_VOTE"]
    }
  ],
  "threshold": 2
}

​

Spending Limits

Spending limits provide controlled access to funds without requiring full transaction approval.

​

Key Features

1. Token-Specific Limits

   • Set limits per token
   • Configure maximum amounts
   • Specify allowed destinations

2. Time-Based Controls

   • ONE_TIME: Single-use limit
   • DAILY: Resets every 24 hours
   • WEEKLY: Resets every 7 days
   • MONTHLY: Resets every 30 days
   • YEARLY: Resets every 365 days

3. Authorized Signers

   • Specify which signers can use the limit
   • Restrict destinations if needed
   • Optional expiration time

​

Example Configuration

POST /api/v1/smart-accounts/{address}/spending-limits
{
  "amount": "1000000000",  // 1000 USDC (6 decimals)
  "token_address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "period": "DAILY",
  "spending_limit_signers": ["signer1...", "signer2..."],
  "destinations": ["allowed_dest1...", "allowed_dest2..."],
  "expiration": 1703980800  // Optional Unix timestamp
}

​

Time Locks

Time locks add a mandatory delay between transaction approval and execution. This security feature provides a window to review and potentially cancel transactions before they are executed.

​

Key Features

1. Configurable Delay

   • Set in seconds
   • Applies to all transactions
   • Can be modified by admin or threshold

2. Transaction Flow

   • Transaction is proposed and approved
   • Must wait for time lock period
   • Can be executed after delay expires
   • Can be cancelled during delay

​

Example Configuration

PATCH /api/v1/smart-accounts/{address}
{
  "time_lock": 86400,  // 24 hours in seconds
  "transaction_signers": ["SIGNER1", "SIGNER2"]  // Must meet threshold
}

​

Important Notes

• Time lock applies to all transactions except admin actions
• Cannot be bypassed once set
• Set to 0 to disable time lock
• Consider operational needs when setting delay
• Longer delays provide more security but less convenience
• Spending limit debits are not affected by time lock

​

Best Practices

1. Admin Control

   • Use admin control for managed accounts
   • Keep admin keys secure and offline
   • Consider using a multisig as admin

2. Permissions

   • Separate duties between signers
   • Limit CAN_INITIATE to trusted parties
   • Have multiple CAN_EXECUTE signers for redundancy

3. Threshold

   • Choose threshold based on security needs
   • Consider operational efficiency
   • Plan for key rotation

4. Spending Limits

   • Use destination restrictions for added security

5. Time Locks

   • Set appropriate delay based on operational needs
   • Consider the time it takes for transactions to be confirmed