권한관리, AccessControl, Pausable

도입

스테이블코인에서 access control은 보안의 중심이다. 누가 mint할 수 있는지, 누가 주소를 freeze할 수 있는지, 누가 전체 transfer를 pause할 수 있는지에 따라 사용자 자금과 merchant settlement가 직접 영향을 받는다. 권한 설계는 컨트랙트 내부 문제가 아니라 운영, support, compliance, dashboard까지 이어지는 제품 설계다.

OpenZeppelin 문서는 access control이 mint, freeze, upgrade 같은 민감한 작업을 누가 수행할 수 있는지 결정한다고 설명한다. 또한 Pausable은 import만으로 동작하지 않고 실제 함수에 whenNotPaused 같은 modifier를 적용해야 한다. 이 강의는 이 두 사실을 stablecoin checkout의 release gate로 바꾼다.

학습 목표

• 역할 기반 권한과 pause 권한의 책임을 분리한다.
• 운영자 키 탈취와 과도한 권한 집중을 위협 모델에 넣는다.
• freeze, pause, upgrade, mint 권한의 범위와 모니터링 신호를 설계한다.

개념 설명

1. Ownable, AccessControl, AccessManager는 운영 복잡도가 다르다

첫 설계 원칙은 "권한을 나누되, 각 권한의 admin도 같이 설계한다"이다. MINTER_ROLE과 FREEZER_ROLE을 나눠도 DEFAULT_ADMIN_ROLE 하나가 둘 다 즉시 바꿀 수 있으면 실제 위험은 admin에 모인다.

2. Stablecoin role matrix

이 표에는 반드시 "금지해야 할 것"이 들어가야 한다. 허용 함수만 적으면 권한 집중을 놓친다. 예를 들어 FREEZER_ROLE은 주소 이동성을 막을 수 있지만, 잔고를 옮기거나 role을 바꾸면 안 된다.

3. DEFAULT_ADMIN_ROLE은 별도 위협 모델로 본다

OpenZeppelin 문서에서는 DEFAULT_ADMIN_ROLE이 다른 role의 admin이고 자기 자신의 admin이기도 하므로 민감한 권한임을 강조한다. Production stablecoin에서는 아래 완화책을 검토한다.

Admin 설계는 "누가 권한을 갖는가"뿐 아니라 "권한 변경이 얼마나 빨리 효력을 갖는가"를 포함한다. Upgrade와 mint 권한이 같은 multisig에 있으면 key compromise 하나가 code와 supply를 동시에 위험하게 만든다.

4. Pause와 freeze는 다르다

Pause는 강력하지만 거칠다. 전체 checkout을 멈추면 신규 피해는 막을 수 있지만 refund, merchant settlement, emergency withdrawal도 같이 막힐 수 있다. 따라서 pause 상태에서도 어떤 함수가 열려 있어야 하는지 미리 정해야 한다.

5. Pausable은 함수마다 적용 범위를 정해야 한다

OpenZeppelin Pausable 문서 기준으로 module을 포함하는 것만으로 함수가 자동으로 멈추지 않는다. whenNotPaused, whenPaused, _requireNotPaused 같은 조건을 어디에 적용할지 설계해야 한다.

중요한 것은 정책을 테스트로 고정하는 것이다. "pause하면 멈춘다"가 아니라 어떤 함수가 revert하고 어떤 함수가 manual review로 넘어가는지를 표로 남긴다.

6. Emergency pause runbook

Runbook에는 unpause 조건도 있어야 한다. Pause는 실행보다 해제가 더 위험할 수 있다. Root cause가 확인되지 않았는데 unpause하면 같은 사고가 반복된다.

7. 테스트와 모니터링 항목

코드로 확인하기

앞의 보안 기준을 코드와 테스트로 확인한다. 함수가 어떤 전제를 세우고, 테스트가 어떤 실패 조건을 고정하는지 함께 읽는다.

컨트랙트OpenZeppelin AccessControl 기반 stablecoin 권한 패턴

Mock 학습용 코드와 달리 실제 배포 후보는 OZ AccessControl을 상속한다. _grantRole로 초기 권한을 분리하고, onlyRole로 함수마다 정확한 역할을 요구한다.

01import {AccessControl} from "@openzeppelin/contracts/access/AccessControl.sol";02import {Pausable} from "@openzeppelin/contracts/utils/Pausable.sol";0304contract StablecoinV2 is AccessControl, Pausable {05    bytes32 public constant MINTER_ROLE   = keccak256("MINTER_ROLE");06    bytes32 public constant BURNER_ROLE   = keccak256("BURNER_ROLE");07    bytes32 public constant FREEZER_ROLE  = keccak256("FREEZER_ROLE");08    bytes32 public constant PAUSER_ROLE   = keccak256("PAUSER_ROLE");09    bytes32 public constant UPGRADER_ROLE = keccak256("UPGRADER_ROLE");1011    constructor(address adminMultisig) {12        _grantRole(DEFAULT_ADMIN_ROLE, adminMultisig);13        // MINTER 등은 adminMultisig가 추후 grantRole 로 분리 부여 — 단일 EOA 집중 방지14    }1516    function mint(address to, uint256 amount) external onlyRole(MINTER_ROLE) whenNotPaused {17        _mint(to, amount);18    }1920    function pause() external onlyRole(PAUSER_ROLE) {21        _pause();22    }23}

컨트랙트Pausable 적용 범위를 함수별로 분기

whenNotPaused는 modifier로 명시한 함수에만 적용된다. burn/refund는 사고 중에도 열어둘 수 있게 정책에 따라 분리한다.

01function transfer(address to, uint256 amount) public override whenNotPaused returns (bool) {02    return super.transfer(to, amount);03}0405function burn(address from, uint256 amount) external onlyRole(BURNER_ROLE) {06    // pause 중에도 redemption은 열어둔다 — whenNotPaused 일부러 누락07    _burn(from, amount);08}0910function refund(bytes32 paymentId) external nonReentrant {11    // refund는 사용자 보호 차원에서 pause 중에도 허용12    Payment storage p = payments[paymentId];13    if (p.status != Status.Paid) revert PaymentNotPaid(paymentId);14    p.status = Status.Refunded;15    IERC20(p.token).safeTransfer(p.payer, p.amount);16}

컨트랙트AccessControlDefaultAdminRules — 2-step + delay

OZ 4.9+의 AccessControlDefaultAdminRules는 DEFAULT_ADMIN_ROLE을 2-step transfer + delay로 보호한다. admin 키 탈취·실수의 충격을 줄인다.

01import {AccessControlDefaultAdminRules}02  from "@openzeppelin/contracts/access/extensions/AccessControlDefaultAdminRules.sol";0304contract StablecoinV2 is AccessControlDefaultAdminRules {05    constructor(address adminMultisig)06        AccessControlDefaultAdminRules(3 days, adminMultisig) // 3일 지연07    {}08    // beginDefaultAdminTransfer → acceptDefaultAdminTransfer 두 단계 + 3일 대기09    // cancelDefaultAdminTransfer 로 취소 가능10}

운영Role 이벤트 모니터링 — viem watcher 예시

권한 변경은 사고 신호다. RoleGranted/Revoked/Paused/Unpaused를 production multisig 가 아닌 곳에서 발생하면 즉시 알림.

01import { createPublicClient, http, parseAbi } from "viem";02import { mainnet } from "viem/chains";0304const TRUSTED_ADMIN = "0xMultisigAddress";05const client = createPublicClient({ chain: mainnet, transport: http() });0607const abi = parseAbi([08  "event RoleGranted(bytes32 indexed role, address indexed account, address indexed sender)",09  "event RoleRevoked(bytes32 indexed role, address indexed account, address indexed sender)"10]);1112client.watchContractEvent({13  address: STABLECOIN_ADDRESS,14  abi,15  eventName: "RoleGranted",16  onLogs: (logs) => {17    for (const log of logs) {18      if (log.args.sender?.toLowerCase() !== TRUSTED_ADMIN.toLowerCase()) {19        pageOncall({ severity: "critical", reason: "RoleGranted by untrusted sender", log });20      }21    }22  }23});

강의 포인트

실무 예시

운영[CONTRACT] 상황: checkout 팀이 PAUSER_ROLE을 backend deployer EOA에 주고, FREEZER_ROLE과 UPGRADER_ROLE도 같은 주소에 두려 한다. 테스트넷에서는 편하지만 production에서는 key 하나가 checkout 전체, 사용자 주소 freeze, implementation upgrade를 동시에 통제한다.

이 예시의 산출물은 코드 수정 제안만이 아니다. Role owner, multisig threshold, timelock delay, pause 대상 함수, unpause 조건을 포함한 운영 문서가 필요하다.

흔한 오해와 실패 시나리오

실습 과제

1. 컨트랙트Stablecoin role matrix 만들기: DEFAULT_ADMIN, MINTER, BURNER, FREEZER, PAUSER, UPGRADER, RELAYER role별 owner, admin role, 허용 함수, 금지 함수, multisig/timelock 요구, dashboard event를 표로 정리한다.
2. 운영Emergency pause runbook 작성하기: pause trigger, 승인자, pause 대상 함수, refund/emergency path, unpause 조건, 사용자 안내, dashboard alert를 단계별로 작성한다.
3. 컨트랙트Freeze/Pause 우회 테스트 설계하기: frozen 또는 paused 상태에서 transfer, transferFrom, approve, permit, ERC-3009, checkout claim/refund가 어떻게 동작해야 하는지 테스트 표로 작성한다.

완료 기준

1. role matrix를 만들었다.
2. pause 범위를 설명했다.
3. 권한 변경 모니터링 항목을 정의했다.
4. emergency pause와 unpause 승인 절차를 runbook으로 작성했다.

근거 자료

• 권한관리 AccessControl Pausable: 02-보안-테스트/02-권한관리-AccessControl-Pausable.md
• OpenZeppelin Contracts: Access Control: https://docs.openzeppelin.com/contracts/5.x/access-control
• OpenZeppelin Contracts API: Access: https://docs.openzeppelin.com/contracts/api/access
• OpenZeppelin Contracts API: Pausable: https://docs.openzeppelin.com/contracts/5.x/api/utils
• OpenZeppelin AccessControlDefaultAdminRules: https://docs.openzeppelin.com/contracts/4.x/api/access#AccessControlDefaultAdminRules