Contract API

페이지네이션 역방향 조회입니다. wallet에 등록된 agent ID 목록을 반환합니다. 마루 Agent 프리컴파일이 이 메서드를 노출하는 이유는 컨트랙트 내부에서 IdentityRegistry 스토리지를 순회하는 비용이 너무 크기 때문입니다. 프리컴파일은 동기화된 x/agent 체인 측 인덱스에서 직접 읽어옵니다. 그 외의 호출(register, attest, 메타데이터)은 IdentityRegistry를 직접 호출합니다.

이 마루 네트워크의 ERC-8004 IdentityRegistry와 ReputationRegistry preinstall 주소를 반환합니다. Discovery 헬퍼 메서드입니다. 앱 시작 시 한 번 호출하면, testnet과 mainnet에서 올바른 레지스트리 주소를 하드코딩 없이 확인할 수 있습니다.

이 마루 네트워크의 정식 EAS 배포 주소들을 반환합니다. SchemaRegistry, EAS 컨트랙트, Indexer 주소가 포함됩니다. 앱 시작 시 한 번 호출하면 testnet과 mainnet 모두에서 하드코딩 없이 올바른 주소를 해결할 수 있습니다. 반환 struct 이름은 EasParams입니다. 여러 프리컴파일 인터페이스를 함께 import할 때 충돌을 피하기 위해 네임스페이스 없는 Params 이름에서 변경되었습니다.

주어진 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)에 전달하여 실제 구조체를 가져오고 폐기/만료 여부를 확인합니다.

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

특정 contractAddress에 부착된 PERIODIC_VOLUME_POLICY에 대해 user의 현재 누적 거래량 카운터를 읽습니다. asset과 resetPeriodSeconds로 조회 범위를 좁히며, 필요하다면 함수 selector로도 좁힐 수 있습니다. selector 없이 등록된 PolicySet(컨트랙트의 모든 호출에 적용되는 정책)을 조회하려면 빈 바이트("0x")를 전달합니다.

체인 바이너리에 내장된 표준 프록시 bytecode로 PCL 래핑 프록시를 배포하고, PCL 프록시 레지스트리에 등록하며, 배포 호출자(msg.sender)를 그 프록시 주소의 초기 PCL 컨트랙트 admin으로 바인딩합니다. 이 모든 작업은 호출이 반환되기 전에 완료됩니다. 초기 admin이 msg.sender로 바인딩되므로, 팩토리 컨트랙트를 통해 배포하면 최종 사용자가 아니라 팩토리가 admin이 됩니다. PclProxyKind.Transparent의 경우 initData는 abi.encode(logic, initialOwner, initializer)입니다.

현재 PCL 모듈 파라미터를 PclParams struct로 반환합니다. 체인 전역 정책 관리자 주소와, AA principal 디코딩을 위해 PCL이 신뢰하는 ERC-4337 EntryPoint 컨트랙트 목록을 포함합니다. Solidity 컨트랙트나 오프체인 클라이언트에서 정책 관리자를 하드코딩하지 않고 조회하거나, 계정 추상화 트랜잭션에서 PCL이 인식하는 EntryPoint 주소를 열거할 때 사용합니다.

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

전역 설정에 등록된 PERIODIC_VOLUME_POLICY 중 지정한 asset과 resetPeriodSeconds에 해당하는 정책에 대해, user의 현재 누적 거래량 카운터를 읽습니다. 현재 누적 금액, 정책 상한, 기간 길이, 현재 윈도가 종료되는 unix 타임스탬프를 반환합니다. 트랜잭션 제출 전 전역 주기 상한에 걸릴지 미리 확인하는 데 사용합니다.

프록시가 구현체에 대한 delegatecall을 마친 뒤, 짝이 되는 preCall이 연 PCL 세션을 닫습니다. postCall은 구현체 내부에서 발생한 전송 로그 델타를 검사해 주기 거래량 누적을 기록하고, AGENT_OKRW_TRANSFER_LIMIT_POLICY, OKRW_EAS_TRANSFER_LIMIT_POLICY 같은 사후 정책을 평가합니다. workable이 false이면(구현체가 이미 revert된 경우) 사후 정책 평가, 거래량 기록, 로그 마킹, 이벤트 발행을 모두 건너뜁니다.

프록시 호출을 위한 PCL 정책 평가 세션을 엽니다. PCL로 래핑된 프록시 훅이 구현체를 delegatecall하기 전에 호출합니다. preCall은 contractAddress에 등록된 ContractPolicyConfig(존재하는 경우)와 체인 전역 GlobalPolicyConfig를 전달된 principal / data / value에 대해 평가하고, 주기 거래량 등 누적형 정책에 필요한 사전 상태를 스냅숏한 뒤, 짝이 되는 postCall이 제시해야 할 sessionId를 반환합니다. 정책 중 하나라도 거절하면 해당 PCL ReasonCode로 revert됩니다.

PCL 프리컴파일의 deployPclProxy로 배포된 프록시의 레지스트리 엔트리를 반환합니다. 현재 엔트리는 프록시 변형을 식별하는 kind 필드 하나만 포함하며, V1에서는 PclProxyKind.Transparent만 등록됩니다. 조회한 주소가 등록된 PCL 래핑 프록시가 아니면 반환된 struct의 모든 필드가 0이며, kind는 PclProxyKind.Unspecified(enum 값 0)로 디코드됩니다.

내장 정책 템플릿을 templateId로 활성 PCL 템플릿 레지스트리에 등록합니다. 7개의 V1 템플릿(DENYLIST_POLICY, VOLUME_POLICY, PERIODIC_VOLUME_POLICY, EAS_POLICY, OKRW_EAS_TRANSFER_LIMIT_POLICY, OKRW_EAS_PERIODIC_VOLUME_LIMIT_POLICY, AGENT_OKRW_TRANSFER_LIMIT_POLICY)이 체인과 함께 출시되며, 이 호출이 그중 하나를 PolicyConfig에서 사용할 수 있도록 만듭니다. 관리자 전용: 호출자는 컨소시엄 거버넌스로 지정된 PolicyAdmin이어야 합니다. 외부 dApp 빌더가 직접 호출할 일은 없으며, 프로토콜 감사 측면과 PolicySet의 templateId가 등록된 템플릿을 참조하는 방식을 명확히 하기 위해 문서에 포함했습니다.

view 호출입니다. contractAddress에 대해 현재 활성화된 컨트랙트 범위 ContractPolicyConfig(즉, admin과 전체 PolicySet[])를 반환합니다. 해당 주소에 등록된 컨트랙트 범위 설정이 없다면 revert하지 않고 zero 값 struct(_contract = address(0), admin = address(0), 빈 policies 배열)를 반환합니다. 이때도 체인 전역 GlobalPolicyConfig는 그 컨트랙트에 계속 적용됩니다. 규제 경로(runOnPcl / PCL 프록시 훅)를 통해 대상 컨트랙트가 강제하는 정확한 규칙을 확인할 때 사용합니다.

view 호출입니다. 7개의 내장 PCL 템플릿 중 하나의 등록 레코드를 templateId로 조회합니다. 알려지지 않은 templateId이면 revert됩니다. 각 템플릿의 파라미터 구조는 IPcl.sol에 고정되어 있으며(예: DenylistPolicy { address[] addresses; }), policyTemplate은 레지스트리 메타데이터만 반환합니다. 파라미터 레이아웃을 알려면 해당 템플릿의 Solidity 구조체를 직접 참조해야 합니다.

PCL의 규제 컨텍스트 안에서 대상 컨트랙트에 대한 호출을 실행합니다. 이 함수는 '규제 트랙'의 진입점입니다. 먼저 발신자, 대상 컨트랙트, 호출 데이터를 기준으로 적용 대상이 되는 전역 및 컨트랙트별 정책 검사를 모두 실행합니다. 모든 검사가 통과하면 저수준 call을 사용하여 대상 컨트랙트에서 제공된 호출 데이터를 실행합니다. 검사 중 하나라도 실패하면 트랜잭션이 해당 오류로 revert됩니다.

ContractPolicyConfig의 레거시 최초 등록 진입점입니다. policy.admin을 policy._contract의 PCL admin으로 바인딩하고 초기 정책 세트를 저장합니다. 이 진입점은 deprecated 상태입니다. admin 슬롯이 이미 바인딩된 경우 현재 바인딩된 admin만 호출할 수 있고, 이때 호출은 전체 재등록을 수행합니다(정책 세트가 교체되고 슬롯이 policy.admin으로 설정되므로 현재 admin이 슬롯을 넘겨줄 수도 있습니다). 바인딩된 admin이 아닌 호출자는 PolicyAlreadyRegistered로 revert됩니다. 새 코드는 changeContractPolicies를 사용합니다.

컨트랙트의 정책 설정 전체를 교체하며, 동일한 호출에서 admin 권한을 이전할 수도 있습니다. 호출자는 policy._contract의 현재 admin이어야 합니다. 성공 시 저장된 PolicySet[]은 policy.policies로 완전히 교체되고 admin 바인딩은 policy.admin으로 설정됩니다. 현재 admin을 유지하려면 policy.admin에 동일한 주소를 전달합니다. 권한을 이전하려면 새 admin의 주소를 전달합니다. 이것이 지원되는 유일한 admin 이전 경로이며, 별도의 transfer 메서드는 없습니다.

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

amount로 지정된 수량의 OKRW 토큰을 발행하여 recipient 주소로 입금합니다. 이 함수는 x/okrw 모듈 파라미터에서 체인 수준으로 지정된 발행자 주소만 호출할 수 있습니다. 다른 주소에서 호출하면 사용자 정의 오류로 revert됩니다.

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