IPcl.globalPeriodicVolume
globalPeriodicVolume(address user, string asset, uint64 resetPeriodSeconds, bool resolveAgentOwners) external view returns (PeriodicVolume memory) 전역 설정에 등록된 PERIODIC_VOLUME_POLICY 중 지정한 asset과 resetPeriodSeconds에 해당하는 정책에 대해, user의 현재 누적 거래량 카운터를 읽습니다. 현재 누적 금액, 정책 상한, 기간 길이, 현재 윈도가 종료되는 unix 타임스탬프를 반환합니다. 트랜잭션 제출 전 전역 주기 상한에 걸릴지 미리 확인하는 데 사용합니다.
파라미터
| 이름 | 타입 | 필수 | 설명 |
|---|---|---|---|
user | address | ✓ | 누적 거래량을 조회할 주소입니다. 일반적으로 곧 제출할 트랜잭션의 msg.sender입니다. |
asset | string | ✓ | 정책의 키가 되는 denom 문자열입니다. OKRW의 경우 base denom인 "aokrw"를 사용합니다. |
resetPeriodSeconds | uint64 | ✓ | 조회할 PERIODIC_VOLUME_POLICY 상한을 식별하는 리셋 주기 길이입니다(예: 24시간은 86400, 30일은 2592000). 대상 정책에 설정된 resetPeriodSeconds와 정확히 일치해야 합니다. |
resolveAgentOwners | bool | ✓ | true이고 user가 에이전트 지갑이면, 에이전트 주소가 아니라 에이전트의 소유자(owner)들을 기준으로 누적 카운터를 집계합니다. false이면 user 주소 자체만 조회합니다. |
반환값
타입:
PeriodicVolume 구조체 { uint256 amount, uint256 maxAmount, uint64 resetPeriodSeconds, uint64 resetAt }입니다. amount는 현재 윈도 내 누적 금액이고, maxAmount는 정책 상한, resetAt은 윈도가 리셋되는 unix 타임스탬프입니다.
예제
전송 전 일일 OKRW 거래량 미리보기
user의 24시간 전역 OKRW 거래량 카운터를 읽습니다. user가 EOA이므로 resolveAgentOwners = false를 사용합니다. 실제 전송 상한(10,000,000 OKRW = 1e7 × 10^18 aokrw)과 잔여 한도를 비교합니다.
import { createPublicClient, http, parseAbi } from "viem";
const PCL = "0x1000000000000000000000000000000000000005";
const pclAbi = parseAbi([
"function globalPeriodicVolume(address user, string asset, uint64 resetPeriodSeconds, bool resolveAgentOwners) view returns ((uint256 amount, uint256 maxAmount, uint64 resetPeriodSeconds, uint64 resetAt))",
]);
const client = createPublicClient({ transport: http("https://rpc-testnet.maroo.io") });
const user = "0x1111111111111111111111111111111111111111"; // replace before production
const v = await client.readContract({
address: PCL,
abi: pclAbi,
functionName: "globalPeriodicVolume",
args: [user, "aokrw", 86_400n, false],
});
const headroom = v.maxAmount - v.amount; // in aokrw
console.log(`used ${v.amount} / ${v.maxAmount} aokrw, resets at ${v.resetAt}`);
if (headroom < 10_000_000n * 10n ** 18n) {
// < 10,000,000 OKRW headroom — this transfer will trip the cap
}에이전트 지갑 카운터를 owner 기준으로 집계
resolveAgentOwners = true를 전달하면 정책 평가기가 에이전트 지갑을 집계하는 방식과 동일하게 동작합니다. 카운터가 에이전트 주소가 아니라 에이전트의 소유자(owner)들 기준으로 집계됩니다. 에이전트가 제어하는 전송을 미리 확인할 때 사용합니다.
const agentWallet = "0x2222222222222222222222222222222222222222"; // replace before production
const v = await client.readContract({
address: PCL,
abi: pclAbi,
functionName: "globalPeriodicVolume",
args: [agentWallet, "aokrw", 86_400n, true],
});
// v.amount now reflects the aggregated 24h volume across the agent's owner(s),
// which is what a PERIODIC_VOLUME_POLICY configured with agent-owner resolution
// evaluates at enforcement time.
console.log(v);