Rayls의 Sovereign Contracts 저장소를 살펴보면서 Private Network Hub(PNH)의 역할별 권한 설정을 확인했다.

단순히 각 역할이 어떤 기능을 수행하는지 소개하는 대신, 실제 구현 코드와 권한 설정 스크립트, 공식 문서가 서로 일치하는지 비교해 봤다.

권한 관리 시스템에서는 역할 이름만 아는 것으로 충분하지 않다. 코드가 어떤 권한을 지원하는지, 설정 스크립트가 어떤 매핑을 실행하는지, 문서가 이를 어떻게 설명하는지까지 함께 살펴봐야 하기 때문이다.

비교 과정에서 확인할 만한 지점 세 가지를 발견했다.

1. 복수 역할 매핑을 지원하는 구현과 주석의 차이

먼저 "src/privateHub/AccessControl/libraries/AccessManagerRoleConfigLib.sol"을 살펴봤다.

이 파일의 "addFunctionAllowedRoles()" 구현은 전달받은 여러 역할 ID를 순회하면서 해당 함수 선택자에 대한 역할 비트맵을 갱신한다.

즉, Rayls의 커스텀 권한 관리 구현은 하나의 함수에 여러 역할을 연결할 수 있는 구조다.

그런데 역할을 활성화하는 "hardhat/tasks/interact/access-control/activate-business-roles-pnh.ts"에는 하나의 함수에 하나의 역할만 매핑할 수 있다는 취지의 주석이 나온다.

여기서 중요한 점은 주석과 실제 구현을 구분해서 읽어야 한다는 것이다.

주석의 설명만 보면 복수 역할 매핑에 제한이 있는 것처럼 이해할 수 있지만, 실제 구현에서는 여러 역할 ID를 처리하는 로직을 확인할 수 있다.

따라서 이 부분은 설정 스크립트의 설명과 실제 권한 관리 구현을 함께 대조해야 하는 지점이다.

2. TOKEN_MANAGER의 권한 설명이 문서마다 다르다

두 번째는 "TOKEN_MANAGER"의 권한 설명이다.

Rayls의 공식 Private Network Roles 문서는 "TOKEN_MANAGER"에 매핑된 함수가 없다고 설명한다.

반면 저장소의 역할 참조 문서에는 "TokenRegistry.updateStatus()"와 "TOKEN_MANAGER"의 연결이 기재되어 있다.

같은 역할을 설명하는 문서 사이에 차이가 존재하는 것이다.

이 차이는 단순한 표현의 문제가 아니다.

개발자가 역할별 권한을 확인하거나 운영자가 설정을 검토할 때, 어느 문서를 기준으로 판단해야 하는지 혼란이 생길 수 있다. 특히 문서만 보고 권한을 파악한다면 실제 코드나 설정과 다른 이해를 할 가능성이 있다.

다만 문서가 서로 다르다는 사실만으로 어느 쪽이 현재 배포 환경의 권한을 정확하게 반영하는지 단정할 수는 없다.

확실하게 말할 수 있는 것은 두 문서의 설명이 서로 일치하지 않으며, 기준이 되는 권한 정보를 명확히 할 필요가 있다는 점이다.

3. TeleportV1.setLockTime()의 출력 요약과 실제 매핑 목록

세 번째는 권한 활성화 스크립트의 출력 요약이다.

"activate-business-roles-pnh.ts"의 마지막 콘솔 출력 요약에는 다음과 같은 매핑이 표시된다.

"TeleportV1.setLockTime() → PRIVATE_NETWORK_OPERATOR"

그런데 스크립트에서 실제 매핑 작업을 담고 있는 "mappingTxs" 목록에서는 이 매핑을 수행하는 호출을 확인할 수 없다.

여기서는 출력 메시지와 실제 실행 작업을 구분해야 한다.

콘솔에 특정 권한 매핑이 표시된다고 해서 그 문구만으로 실제 매핑 트랜잭션이 실행됐다고 판단할 수는 없다. 실행하려는 작업 목록과 결과를 설명하는 출력 요약은 서로 다른 역할을 하기 때문이다.

따라서 이 항목은 설정 스크립트의 출력과 실제 매핑 목록을 대조해 볼 필요가 있는 사례다.

다만 이 코드만으로 실제 배포된 네트워크에서 "TeleportV1.setLockTime()" 권한이 설정되어 있는지, 또는 설정되어 있지 않은지까지 결론 내릴 수는 없다. 그 부분은 별도의 온체인 조회로 검증해야 한다.

세 가지 발견에서 공통으로 보이는 점

이번에 비교한 내용은 서로 다른 유형의 불일치다.

- 구현과 주석: 실제 코드가 지원하는 구조와 주석의 설명을 대조해야 한다.

- 문서와 문서: 같은 역할에 대해 서로 다른 권한 정보를 제공하고 있다.

- 출력 요약과 실행 목록: 표시된 설명만으로 실제 실행 여부를 판단해서는 안 된다.

이 세 가지를 같은 종류의 오류라고 단정할 수는 없다. 하지만 모두 권한 설정을 검토할 때 설명 문구만 읽는 것으로는 충분하지 않다는 점을 보여준다.

코드가 지원하는 기능, 설정 스크립트가 실행하는 작업, 문서가 설명하는 권한은 서로 연결되어 있어야 한다. 이 정보가 어긋나면 개발자와 운영자가 의도된 권한 구조를 정확하게 이해하기 어려워질 수 있다.

결론

이번 조사의 핵심은 Rayls의 권한 관리 시스템에 문제가 있다고 단정하는 것이 아니다.

실제 구현 코드와 설정 스크립트, 문서를 비교해 어디에서 설명이 서로 달라지는지 구체적으로 찾아냈다는 것이다.

그리고 소스 코드에서 확인한 사실과 별도의 검증이 필요한 사항을 구분하는 것도 중요하다. 저장소에서 불일치를 발견했다고 해서 실제 배포 환경에서도 동일한 문제가 발생한다고 볼 수는 없기 때문이다.

인프라를 제대로 이해하려면 기능 설명을 읽는 데서 멈추지 않고, 코드와 설정을 직접 대조해야 한다.

이번 비교를 통해 다시 확인한 것도 바로 그 점이다.

#RLS