​

TIP-1011: Enhanced Access Key Permissions

​

Abstract

​

Motivation

​

Periodic Spending Limits

• A service needs recurring access to a fixed amount per billing cycle
• Users want to authorize “up to X tokens per month” without re-authorizing
• dApps implement subscription models (e.g., streaming services, SaaS payments)

1. Subscription services: Authorize a streaming service to charge 10 USDC/month
2. Recurring donations: Allow an NPO to withdraw up to 5 USDC weekly
3. Payroll systems: Enable payroll contracts to transfer salaries monthly
4. Rate-limited APIs: Authorize API access keys with per-period token budgets

​

Destination Address Scoping

1. DeFi integrations: Allow a trading bot key to only interact with specific DEX contracts
2. Gaming: Scope a session key to only interact with a game contract
3. Subscription services: Allow a key to only call a specific payment contract

​

Specification

​

Extended Data Structures

​

TokenLimit

struct TokenLimit {
    address token;
    uint256 limit;
}

struct TokenLimit {
    address token;
    uint256 limit;      // Per-period limit when period > 0, one-time limit otherwise
    uint256 remainingInPeriod;  // Remaining allowance in current period
    uint64 period;      // Period duration in seconds (0 = one-time limit)
    uint64 periodEnd;   // Timestamp when current period expires
}

​

KeyAuthorization

• spendingLimits: TokenLimit[]
• expiry: uint64

struct KeyAuthorization {
    TokenLimit[] spendingLimits;
    uint64 expiry;
    address[] allowedDestinations; // Empty array = unrestricted
}

​

Interface Changes

​

IAccountKeychain.sol

/// @notice Authorizes a key with enhanced permissions
/// @param key The public key to authorize
/// @param expiry Block timestamp when key expires
/// @param spendingLimits Token spending limits (may include periodic limits)
/// @param allowedDestinations Addresses the key may call (empty = unrestricted)
function authorizeKey(
    bytes calldata key,
    uint64 expiry,
    TokenLimit[] calldata spendingLimits,
    address[] calldata allowedDestinations
) external;

/// @notice Returns the allowed destinations for a key
/// @param key The public key to query
/// @return destinations Array of allowed destination addresses (empty = unrestricted)
function getAllowedDestinations(bytes calldata key) external view returns (address[] memory destinations);

/// @notice Returns the remaining limit for a token, accounting for period resets
/// @param key The public key to query
/// @param token The token address
/// @return remaining The remaining spending limit for the current period
/// @return periodEnd The timestamp when the current period ends (0 if one-time limit)
function getRemainingLimit(bytes calldata key, address token) external view returns (uint256 remaining, uint64 periodEnd);

​

Semantic Behavior

​

Periodic Limit Reset Logic

function verifyAndUpdateSpending(key, token, amount):
    limit = getTokenLimit(key, token)
    
    if limit.period > 0:  // Periodic limit
        if block.timestamp >= limit.periodEnd:
            // Reset period
            limit.periodEnd = block.timestamp + limit.period
            limit.remainingInPeriod = limit.limit  // Reset to per-period allowance
    
    if amount > limit.remainingInPeriod:
        revert SpendingLimitExceeded()
    
    limit.remainingInPeriod -= amount

​

Destination Validation Logic

function validateDestination(key, destination):
    allowed = getAllowedDestinations(key)
    
    if allowed.length == 0:
        return true  // Unrestricted
    
    for addr in allowed:
        if addr == destination:
            return true
    
    revert DestinationNotAllowed()

​

Interaction Rules

1. Mixed limits: Keys can have a mix of one-time and periodic limits for different tokens
2. Destination + limits: Both constraints are evaluated independently; both must pass
3. Period updates: Calling updateSpendingLimit() updates the per-period amount and resets the current period
4. Empty destinations: An empty allowedDestinations array means the key is unrestricted (can call any address)

​

Gas Costs

​

Backward Compatibility

​

RLP Encoding Changes

​

TokenLimit (2 fields → 5 fields)

On decode:
  if list.len() == 2:
    // V1 (legacy one-time limit)
    remainingInPeriod = limit
    period = 0
    periodEnd = 0
  else if list.len() == 5:
    // V2 (periodic limit)
    decode all fields
  else:
    error

​

KeyAuthorization (trailing field addition)

• Old encodings (without allowedDestinations) decode as allowedDestinations = None (unrestricted)
• New encodings with allowedDestinations will be rejected by old nodes

​

Precompile Storage Changes

• keys[account][keyId] → AuthorizedKey (packed slot)
• spending_limits[key][token] → U256 (remaining amount)

​

Hardfork-Gated Features

1. RLP decoding: Accept 5-field TokenLimit and allowedDestinations in KeyAuthorization
2. Periodic limit reset logic: Check periodEnd and reset remainingInPeriod on spend
3. Destination scoping enforcement: Validate transaction to against allowedDestinations
4. New precompile storage writes: Write to new storage slots for period/destination data
5. New precompile interface methods: getAllowedDestinations(), updated getRemainingLimit() return type

​

Invariants

1. Period monotonicity: periodEnd MUST only increase; it cannot be set to a past timestamp.
2. Limit conservation: For periodic limits, remainingInPeriod MUST NOT exceed limit after any reset.
3. Destination enforcement: If allowedDestinations is non-empty, transactions to addresses not in the list MUST revert.
4. Backward compatibility: Keys authorized without the new fields MUST behave as unrestricted (allowedDestinations = []) with one-time limits (period = 0).
5. Expiry precedence: Key expiry MUST be checked before spending limits or destination restrictions.