Contract API

체인 단위 정책 관리자가 내장 PCL 정책 템플릿을 활성 레지스트리에 추가하거나 제거하는 작업입니다. registerPolicyTemplate은 템플릿 ID를 PolicySet으로 인스턴스화할 수 있게 만들며, removePolicyTemplate은 이를 회수합니다. IPcl.policyAdmin()이 반환하는 주소만 호출할 수 있으며, 다른 호출자는 Unauthorized()로 revert됩니다. 관리자가 PCL 프리컴파일에 대해 두 호출을 수행하면 관리자 복구 경로에 의해 PCL 정책 평가가 우회되므로, 관리자 자신의 주소를 거절할 수 있는 잘못 구성된 전역 정책이 있어도 차단되지 않습니다.

컨트랙트 범위 정책 바인딩에 대한 두 작업입니다. contractPolicies(address)는 현재 바인딩된 ContractPolicyConfig를 반환하는 view입니다. 바인딩이 없으면 0으로 채운 struct가 반환됩니다. removeContractPolicies(address)는 PCL 래핑 프록시의 PolicySet[]을 비웁니다. 컨트랙트 admin 바인딩 자체는 제거하지 않으므로, admin은 이후 changeContractPolicies로 다시 정책을 붙일 수 있습니다. 보호 장치가 두 가지 있습니다. (1) 현재 컨트랙트 admin만 제거할 수 있습니다. (2) 정책 인지 프리컴파일(PclParams.PolicyAwarePrecompiles에 등재된 주소)은 이 방식으로 비울 수 없습니다. 이 경우 CannotEmpty("policy-aware precompile policies")로 revert됩니다. 정책 인지 프리컴파일의 규칙을 완화하려면 대신 changeContractPolicies로 허용형 PolicySet을 설정합니다.

등록된 PCL 정책 템플릿의 디스크립터를 반환합니다. 반환되는 PolicyTemplate struct는 templateId, name, description 세 필드만 담는 메타데이터 전용 구조이며, 기계가 읽을 수 있는 파라미터 스키마는 포함하지 않습니다. 각 템플릿의 파라미터 형태는 IPcl.sol의 템플릿별 struct(DenylistPolicy, EasPolicy 등)에서 확인합니다. 요청한 templateId가 현재 네트워크에 등록되어 있지 않으면 PolicyTemplateNotFound로 revert됩니다.

대상 주소의 ContractPolicyConfig를 upsert합니다. 대상은 deployPclProxy로 배포한 PCL 등록 프록시이거나, 바이너리가 지원하는 정책 인식 프리컴파일이어야 합니다. 정책 인식 프리컴파일은 현재 0x100000000000000000000000000000000000000b의 Privacy 프리컴파일 하나입니다. 특정 대상에 대한 최초 호출에서는 msg.sender가 누구든 가능하며, 페이로드의 admin이 이후 게이트키퍼가 됩니다. 이후 호출에서는 msg.sender가 저장된 현재 admin과 같아야 하고, 페이로드의 새 admin 값이 정책 교체와 함께 원자적으로 이전 값을 대체합니다. 정책 인식 프리컴파일에 빈 policies 배열을 전달하는 호출은 거절됩니다. 해당 대상은 항상 최소 하나 이상의 PolicySet을 유지해야 합니다. 일반 PCL 프록시는 빈 policies 배열을 허용하며, 이는 컨트랙트 범위 규칙이 없는 상태와 같습니다. 체인 전역 policyAdmin은 저장된 컨트랙트 admin과 우연히 같은 주소가 아닌 이상 이 설정을 변경할 수 없습니다.

요청한 kind의 PCL 래핑 프록시를 체인 바이너리에 내장된 표준 바이트코드로 배포하고, 온체인 프록시 레지스트리에 등록하며, 직접 호출자(msg.sender)를 초기 정책 관리자로 설정합니다. 반환된 proxy 주소가 dApp이 표준 컨트랙트 주소로 공개해야 할 주소입니다. 이 등록된 프록시를 경유하는 호출만 컨트랙트 범위 PCL 강제 경로(preCall / postCall)를 발동시키기 때문입니다. 배포 후 IPcl.pclProxy(proxy)는 프록시의 kind, 현재 admin, 프록시 주소 자체를 담은 레지스트리 엔트리를 반환합니다. changeContractPolicies로 컨트랙트 관리자를 인계하면 이 admin 필드도 함께 갱신됩니다.

preCall이 연 PCL 강제 세션을 종료합니다. preCall이 반환한 sessionId를 받아, 세션에 저장된 컨텍스트를 사용해 정책 평가의 사후 단계를 실행합니다. 주기 거래량을 기록하고, 사후 규칙을 강제하며, PolicyCheckPassed를 발행합니다. 프리컴파일은 postCall의 직접 호출자(msg.sender), 대상 contractAddress, 전달된 principal, 그리고 data의 선행 4바이트 selector가 모두 세션 개시 시점에 저장된 값과 일치하는지 확인하며, 하나라도 어긋나면 Unauthorized로 revert됩니다. PCL 래핑 프록시는 내부 호출이 반환된 뒤 이 훅을 자동으로 호출합니다. 직접 호출하는 경우에는 postCall에 넘기는 튜플이 preCall에 넘긴 튜플과 바이트 단위로 동일해야 하며, 그렇지 않으면 세션을 종료할 수 없습니다.

규제 대상 호출에 대해 PCL 강제 세션을 엽니다. 직접 호출자(msg.sender)는 두 종류 중 하나여야 합니다. 자기 자신을 대상으로 호출하는 PCL 등록 프록시(contractAddress == msg.sender)이거나, 거버넌스가 신뢰하는 ERC-4337 EntryPoint가 번들을 실행하는 경우입니다. 두 경우 모두 PCL은 전달된 principal(호출을 시작한 EOA 또는 스마트 계정)을 기준으로 전역·컨트랙트 범위 정책을 평가하며, 데이터에서 추출한 4바이트 selector와 value를 사용합니다. 실행 전 정책 중 하나라도 실패하면 해당 PCL ReasonCode로 revert됩니다. 통과하면 PCL은 내부 트레이서를 설치하고, 파생된 sessionId를 키로 세션을 등록한 뒤 반환합니다. 이어지는 postCall 호출은 동일한 sessionId를 제시해 세션을 닫고 실행 후 평가를 수행해야 합니다. staticcall(readonly) 실행에서는 영값 bytes32를 반환하며 세션을 열지 않습니다. 정책 상태는 캐시된 컨텍스트에서 평가된 뒤 폐기됩니다.

PCL 래핑 프록시 주소의 온체인 레지스트리 항목을 반환합니다. PclProxyEntry 튜플은 프록시 변형(kind), 현재 바인딩된 정책 admin(admin), 등록된 프록시 주소(proxy)를 담습니다. proxy가 등록되어 있지 않으면 반환 항목의 모든 필드가 0입니다(kind = Unspecified, admin = 0x0, proxy = 0x0). 호출은 revert되지 않습니다. admin 필드는 표준 컨트랙트 admin 레코드의 투영이며, deployPclProxy 실행 시점에 설정되고 이후 changeContractPolicies가 admin을 회전하면 함께 갱신됩니다. 따라서 클라이언트가 이 뷰만 읽어도 contractPolicies를 추가로 조회하지 않고 현재 게이트키퍼를 확인할 수 있습니다.

contractAddress에 부착된 PERIODIC_VOLUME_POLICY 카운터 중 user에 적용되는 항목 전체를 반환합니다. asset으로 필터링하며, 필요하다면 함수 selector로도 필터링할 수 있습니다. selector 없이 등록된 PolicySet에 매치하려면 빈 바이트("0x")를 전달합니다. 컨트랙트에 설정된 서로 다른 리셋 주기 버킷마다 항목 하나씩 포함됩니다.

contractAddress에서 user에 대해 요청한 (selector, asset, resetPeriodSeconds) 튜플과 일치하는 모든 컨트랙트 범위 주기 거래량 카운터를 반환합니다. 동일한 주기에 서로 다른 maxAmount 한도가 여러 개 등록될 수 있으므로(예: 함수별 상한 아래에 지갑 등급 상한이 겹쳐 있는 경우), 호출자는 단일 레코드를 가정하지 말고 반환 배열을 순회하여 결합해야 합니다. 빈 배열은 해당 튜플에 컨트랙트 정책이 등록되어 있지 않다는 뜻입니다. 함수 selector 범위 없이 등록된 카운터를 조회하려면 빈 selector를 전달합니다. resolveAgentOwners = true이면 user가 소유한 모든 에이전트의 거래량을 합산합니다.

전역 정책 설정에서 user에 적용되는 모든 PERIODIC_VOLUME_POLICY 카운터를 반환합니다. 서로 다른 리셋 주기 버킷마다 항목 하나씩 포함됩니다. 동일 자산에 24시간 상한과 30일 상한이 함께 적용되는 등, 여러 전역 주기 상한을 한 번에 표시하거나 검사할 때 사용합니다.

요청한 (asset, resetPeriodSeconds) 쌍에 해당하는 모든 전역 주기 거래량 카운터를 user에 대해 반환합니다. 전역 PERIODIC_VOLUME_POLICY 중 해당 (자산, 주기) 튜플과 일치하는 정책이 없으면 빈 배열을 반환합니다. 그렇지 않으면 등록된 각 한도마다 하나씩 PeriodicVolume 항목을 담습니다. 동일한 주기에 서로 다른 maxAmount 값이 여러 개 등록될 수 있으며, 호출자가 그중 가장 엄격한 한도를 선택할 수 있도록 모두 반환합니다. resolveAgentOwners를 true로 설정하면 조회 주소가 소유한 모든 에이전트의 거래량을 합산합니다.

PCL 모듈의 런타임 파라미터를 PclParams struct로 반환합니다. 필드는 두 개입니다. policyAdmin은 정책 템플릿을 등록/제거하고 전역 GlobalPolicyConfig를 설정할 수 있는 주소이며, entrypoints는 PCL 평가기가 정당한 최상위 호출자로 인식하는 주소들입니다. 정책 인식 프리컴파일 집합은 더 이상 이 파라미터에 포함되지 않습니다. 체인 바이너리에 고정되어 있으며 내부적으로 types.IsSupportedPolicyAwarePrecompile로 조회되므로, 모듈 파라미터로 재구성할 수 없습니다.

OKRW 모듈 파라미터를 반환합니다. 지정된 발행자 주소와 발행 denom이 포함됩니다. 반환 struct 이름은 OkrwParams입니다. 여러 프리컴파일 인터페이스를 함께 import할 때 struct 이름 충돌을 피하기 위해 네임스페이스 없는 Params 이름에서 변경되었습니다. 발행자 주소 교체는 컨소시엄 거버넌스 작업이며, 클라이언트는 이 함수를 읽기 전용 조회 엔드포인트로 사용합니다.

amount만큼의 OKRW를 발행하여 recipient에게 입금합니다. 금액 단위는 소수점 18자리 base denom인 aokrw입니다. x/okrw 모듈 파라미터에 지정된 발행자 주소만 호출에 성공하며, 그 외 호출자는 모듈 소유 커스텀 오류 UnauthorizedMinter(address caller, address authorizedMinter)로 revert됩니다. recipient가 0 주소이거나 amount가 0이면 공통 오류 IPrecompile.InvalidAddress(string bad)와 IPrecompile.InvalidAmount(string amount)로 각각 revert됩니다. 두 오류 모두 페이로드가 address 또는 uint256이 아니라 문자열로 표현된 값이라는 점에 주의합니다. amount가 nil이거나 음수인 경우(저수준 ABI 조작으로만 도달 가능)는 커스텀 오류가 아니라 각각 "amount must not be nil", "amount must not be negative"라는 일반 문자열 revert로 처리됩니다.

mint 함수가 성공적으로 호출되면 OKRW 프리컴파일이 발생시킵니다. 이 이벤트는 EVM에서 일어난 모든 OKRW 발행 활동을 검증 가능하게 온체인 기록으로 남깁니다. 인덱서와 클라이언트 애플리케이션은 이 이벤트를 구독하여 OKRW 공급 및 분배를 추적할 수 있습니다.

이 체인의 표준 Ethereum Attestation Service 주소를 반환합니다. 반환값은 schemaRegistry, eas, indexer preinstall 주소입니다. 네트워크별로 주소를 하드코딩하는 대신 런타임에 해석하도록 시작 시점에 호출합니다. 이 프리컴파일은 공유 IPrecompile 오류 인터페이스를 상속합니다. 인자 형태 오류는 타입 지정 오류로 revert되지만, keeper가 초기화되지 않은 경우에는 여전히 평문 문자열 "eas keeper is not initialized"로 revert됩니다.

주어진 UID에 대한 전체 Attestation 구조체를 반환합니다. UID가 알려지지 않은 값이면 uid == 0x00..인 Attestation이 반환됩니다. EAS 컨트랙트 preinstall의 정식 read 메서드이며, 다른 모든 surface(@ethereum-attestation-service/eas-sdk, Indexer, PCL EAS_POLICY 평가자)도 결국 이 함수를 호출합니다. dApp 코드는 attestation을 유효한 것으로 취급하기 전에 revocationTime == 0과 (expirationTime == 0 || expirationTime > now) 조건을 함께 검증해야 합니다.

schemaUid로 recipient에게 발급된 attestation 개수를 반환합니다. 저렴한 존재 확인용입니다. getReceivedAttestationUIDs로 페이지네이션하기 전에 먼저 호출합니다. 카운트는 발급만 추적하며 폐기되거나 만료된 attestation도 카운트에 포함되므로, 이 값은 유효성 게이트가 아닌 검색 범위 산정용으로만 사용해야 합니다.

페이지네이션 역방향 조회입니다. schemaUid로 recipient에게 발급된 attestation UID를 최대 length개 반환합니다. reverseOrder = true를 지정하면 가장 최근 항목부터 조회합니다. 반환된 각 UID를 EAS.getAttestation(uid)에 전달하여 실제 구조체를 가져오고 폐기/만료 여부를 확인합니다.

지갑에 등록된 agent ID를 페이지네이션으로 반환하는 역방향 조회입니다. IdentityRegistry 스토리지를 컨트랙트 내부에서 순회하는 비용이 너무 크기 때문에 Agent 프리컴파일이 이 메서드를 제공하며, 프리컴파일은 동기화되어 유지되는 체인 측 인덱스에서 읽습니다. 등록, attestation, 폐지, 메타데이터 등 그 외의 작업은 0x8004000000000000000000000000000000000001의 ERC-8004 IdentityRegistry preinstall을 직접 호출합니다.

Agent 모듈이 이 체인에서 해석하는 표준 주소를 반환합니다. 반환값은 ERC-8004 identityRegistry와 reputationRegistry preinstall 주소입니다. dApp이 네트워크마다 주소를 하드코딩하지 않아도 되도록 시작 시점에 한 번 호출합니다. 이 프리컴파일은 공유 IPrecompile 오류 인터페이스를 상속하므로, 실패는 별도로 정의된 오류가 아니라 공유 타입 지정 오류로 반환됩니다.

호출자의 공개된 OKRW(msg.value로 첨부)를 셸디드 풀에 예치하고, request의 노트 커밋먼트를 Merkle 트리에 추가합니다. deposit은 IPrivacy에서 유일하게 payable인 메서드입니다. 셸디드 금액은 64비트 필드로 제한되므로, 한 번의 deposit은 최대 18446744073709551615 base 단위(약 18.446744073709551615 OKRW)입니다. 더 큰 잔액은 여러 노트로 보관합니다. 실패는 IPrivacy의 타입 지정 커스텀 오류 또는 IPrecompile의 상속 오류로 revert됩니다.

하나 이상의 셸디드 노트를 소비하고 Groth16 증명으로 새 노트를 생성합니다. msg.sender가 effective sender이며, PCL은 호출자를 기준으로 정책을 평가합니다. 실패는 IPrivacy에 선언된 타입 지정 커스텀 오류(요청 만료, nullifier/커밋먼트 충돌, Merkle 용량, 트랜잭션당 한도) 또는 IPrecompile에서 상속된 오류로 revert됩니다. PCL 정책 실패는 그 대신 IPcl의 PCL ReasonCode로 노출됩니다.

셸디드 노트를 소비하고 대응하는 공개된 OKRW를 request.recipient에게 지급합니다. PCL 정책 목적에서 msg.sender가 effective sender입니다. 실패는 IPrivacy에 선언된 타입 지정 커스텀 오류(요청 만료, 네이티브 denom 불일치, nullifier 충돌) 또는 IPrecompile의 상속 오류(InvalidAmount, InvalidAddress 등)로 revert됩니다.

EIP-712 PrivacyActionAuthorization에 서명한 effectiveSender를 대신하여 셸디드 transfer를 실행합니다. 릴레이어가 msg.sender이며, authorization이 nonce가 소비되고 PCL 규칙이 적용되는 발신자를 지정합니다. 실패는 이제 IPrivacy의 타입 지정 커스텀 오류(authorization 검사, 요청 만료, nullifier/커밋먼트 충돌, 배치 한도) 또는 IPrecompile의 상속 오류(InvalidNumberOfArgs, RequesterIsNotMsgSender 등)로 revert됩니다. PCL 정책 실패는 여전히 IPcl의 PCL ReasonCode로 노출됩니다.

effectiveSender가 서명한 EIP-712 인증을 사용하여 실드 풀의 자금을 투명한 EVM 수신자에게 대리 인출합니다. executor(일반적으로 릴레이어)가 트랜잭션을 제출하며, 프리컴파일이 서명을 검증하고 nonce와 deadline으로 재사용을 차단한 뒤 직접 withdraw 메서드와 동일한 널리파이어 소비 상태 전이를 수행합니다. amount 필드는 체인이 파싱하는 코인 문자열입니다(예: 10 OKRW는 "10000000000000000000aokrw").

여러 개의 독립적으로 증명된 셸디드 transfer를 단일 트랜잭션 내에서 원자적으로 적용하며, 모두 batchId로 묶입니다. 각 항목은 배치 전체를 기준으로 중복 nullifier, 중복 커밋먼트, Merkle 용량이 사전 점검됩니다. 어느 하나라도 실패하면 호출 전체가 revert됩니다. 실패는 IPrivacy의 타입 지정 커스텀 오류 또는 IPrecompile의 상속 오류로 노출됩니다.

하나 이상의 실효 발신자를 대신해 다중 증명 배치를 제출합니다. items[i]는 PrivacyTransferRequest와 PrivacyActionAuthorization을 함께 담으며, 인가 서명은 공유된 batchId와 아이템별 batchItemIndex 아래에서 해당 아이템의 요청을 서명합니다. 호출자(msg.sender)는 모든 인가의 executor로 기록됩니다. 복원된 서명자와 authorization.effectiveSender 불일치, deadline 만료, nonce 재사용은 배치 전체를 revert시킵니다. 20개 아이템 프로토콜 제한(MaxPrivacyMultiProofBatchItems)은 직접 호출 경로인 batchTransfer와 동일하게 적용됩니다.

다중 입력·다중 출력의 배치 join-split을 단일 Groth16 증명으로 검증하여 적용합니다. 입력 개수는 1..BatchJoinSplitV1MaxInputs, 출력 개수는 1..BatchJoinSplitV1MaxOutputs 범위여야 합니다. 범위를 벗어나면 PrivacyBatchSizeOutOfRange(count, max)로 revert됩니다. 실패는 IPrivacy의 타입 지정 커스텀 오류 또는 IPrecompile의 상속 오류로 노출됩니다.

singleProofBatchTransfer의 메타 트랜잭션 변형입니다. 릴레이어가 authorization.effectiveSender를 대신하여 배치를 제출하며, 서명자는 요청 해시를 특정 executor·nonce·deadline에 묶어 오프체인에서 서명해 둡니다. authorization.authorizationKind에 따라 EOA 서명, ERC-1271 스마트 계정 서명, EIP-7702 위임 EOA 서명을 지원합니다. 요청 해시 도메인은 이 단일 증명 배치 메서드 전용이라 다른 프라이버시 호출용 인가와 충돌하지 않습니다. 실패는 타입 지정 커스텀 오류로 revert됩니다. IPrivacy가 자체 오류를 선언하고, 공유 프로토콜 오류는 IPrecompile에서 상속하므로, 클라이언트는 사유 문자열을 맞춰보는 대신 4바이트 selector를 디코딩합니다. 한 가지만 여전히 일반 문자열입니다. EOA 서명이 정확히 65바이트가 아니면 타입 오류를 만들기 전에 거부됩니다.