AGENT_OKRW_TRANSFER_LIMIT_POLICY

component compliance

에이전트 지갑의 건당 OKRW 전송 상한을 적용하는 템플릿입니다. 정책 파라미터가 없으며, 한도는 온체인 에이전트 메타데이터(TransferLimit)에서 읽어옵니다.

에이전트 지갑이 수행하는 단일 OKRW 전송에 대해, ERC-8004 IdentityRegistry의 온체인 메타데이터(getMetadata(agentId, "TransferLimit"))에 저장된 한도를 적용합니다. 정책 struct 자체에는 설정 필드가 없으며, 상한은 에이전트 소유자가 메타데이터에 입력한 값을 그대로 사용합니다. 비에이전트 발신자에게는 적용되지 않습니다. 사람이 제어하는 계정은 막지 않으면서 에이전트(자동화된 키)가 한 트랜잭션당 옮길 수 있는 가치의 상한을 부과할 때 사용합니다.

Solidity struct & ABI tuple

IPcl.sol에서:

// 한도는 에이전트 "TransferLimit" 메타데이터에서만 강제. Solidity는 빈 struct를 허용하지
// 않으므로 `reserved` 필드를 두지만 체인은 이 값을 무시 (호출자는 0을 넘겨도 됨).
struct AgentOkrwTransferLimitPolicy {
    uint256 reserved;
}

ABI 튜플 약칭: (uint256 reserved).

PolicySet.policy용 인코딩:

AgentOkrwTransferLimitPolicy memory p = AgentOkrwTransferLimitPolicy({
    reserved: 0   // 무시됨 — Solidity가 빈 struct를 금지하기 때문에 존재할 뿐
});
bytes memory policyBytes = abi.encode(p);
// PolicySet.templateId = "AGENT_OKRW_TRANSFER_LIMIT_POLICY"

에이전트별 한도는 정책 안에 없습니다. 해당 agent ID의 IdentityRegistry 메타데이터 키 "TransferLimit"에 32바이트 uint256을 써서 설정합니다.

정책 평가 방식

각 네이티브 OKRW 전송에 대해 다음 단계를 거칩니다.

1. 발신자 지갑에 등록된 agent ID 목록을 조회합니다(Agent 프리컴파일과 x/agent 인덱스를 통해).
2. 발신자가 소유한 agent ID가 없으면 검사를 건너뜁니다(비에이전트 지갑에는 적용되지 않습니다).
3. 소유한 각 agent ID에 대해 IdentityRegistry.getMetadata(agentId, "TransferLimit")를 읽어와 32바이트 uint256으로 파싱합니다.
4. 유효 상한은 지갑이 소유한 모든 agent ID에 대한 최솟값으로 결정됩니다(가장 엄격한 값이 승리).
5. value > cap이면 ExceededAgentTransferLimit(maxLimit, value)로 거절됩니다.

비-OKRW 자산은 이 템플릿의 검사 대상이 아니며, 네이티브 denom만 측정합니다.

거절 시 발생하는 ReasonCode

ExceededAgentTransferLimit(uint256 maxLimit, uint256 value) — 에이전트의 TransferLimit 메타데이터에 의해 거절된 경우입니다. 지갑 UX는 "이 에이전트의 트랜잭션당 상한은 X입니다. 소유자 계정에서 상한을 올리거나 다른 서명자를 사용합니다"와 같이 안내할 수 있습니다.
AgentTransferLimitMetadataInvalid(string reason) — 메타데이터가 존재하지만 파싱 가능한 32바이트 uint256이 아니거나, 정책이 값을 기대하는데 비어 있는 경우입니다. 거의 항상 설정 버그이므로 최종 사용자가 아닌 운영자에게 노출하는 것이 적절합니다.
AgentKeeperRequired() — 내부 오류로, 에이전트 keeper가 연결되지 않은 상태에서 PCL이 호출된 경우 발생합니다(체인 설정 오류).

한도 설정

상한은 정책별이 아닌 에이전트별로 IdentityRegistry에서 구성합니다.

// 에이전트 소유자 지갑에서
IIdentityRegistry registry = IIdentityRegistry(0x8004000000000000000000000000000000000001);

// 1,000,000 OKRW 상한, 32바이트 big-endian uint256
bytes32 limit = bytes32(uint256(1_000_000 ether));
registry.setMetadata(agentId, "TransferLimit", abi.encodePacked(limit));

메타데이터를 지우거나 0으로 설정하면 이 템플릿이 강제하는 전송 한도가 없어집니다 — 단, 등록된 다른 정책 (OKRW_EAS_TRANSFER_LIMIT_POLICY, VOLUME_POLICY)은 계속 적용됩니다.

주요 활용 사례

이 템플릿은 다음 세 가지 흐름에서 가장 자주 사용됩니다.

에이전트 예산 상한 — 자동화된 트레이딩이나 트레저리 봇용 에이전트 지갑을 전송당 10,000,000 OKRW 정도로 상한을 두면, 키가 침해되어도 한 트랜잭션으로 원금을 모두 빼낼 수 없습니다.
소유자 제어 튜닝 — 상한이 메타데이터에 묶여 있으므로 사람 소유자가 PCL 거버넌스를 거치지 않고도 직접 상한을 올리거나 내릴 수 있습니다.
OKRW_EAS_PERIODIC_VOLUME_LIMIT_POLICY와 결합 — 에이전트 지갑에 건당 한도와 주기 누적 한도를 함께 적용하여 두 계층의 가드를 구성합니다.

Solidity struct & ABI tuple

정책 평가 방식

거절 시 발생하는 ReasonCode

한도 설정

주요 활용 사례

관련 개념