IShAgent Interface

Agent Functions

Agent functions allow policy agents to manage or move tokens on behalf of users, subject to the constraints of the policy. These functions are designed to offer guarantees to agents operating under the constraints of asynchronous execution.

---

hold

function hold(
    uint64 policyID,
    address account,
    uint256 amount
) external;

Places a "hold" on amount of a user’s bonded tokens under a specific policy, preventing them from being moved or unbonded until released.

note

Holds are meant to be issued and expire inside of the same transaction, and are typically used to proactively prevent double-spending.

release

function release(
    uint64 policyID,
    address account,
    uint256 amount
) external;

Releases a previously placed "hold" on amount of a user’s bonded tokens, making those tokens freely available to move or unbond again.

---

batchHold

function batchHold(
    uint64 policyID,
    address[] calldata accounts,
    uint256[] memory amounts
) external;

Performs multiple hold operations in one transaction, holding tokens for multiple accounts.

batchRelease

function batchRelease(
    uint64 policyID,
    address[] calldata accounts,
    uint256[] calldata amounts
) external;

Performs multiple release operations in one transaction, releasing tokens for multiple accounts.

---

agentTransferFromBonded

function agentTransferFromBonded(
    uint64 policyID,
    address from,
    address to,
    uint256 amount,
    uint256 fromReleaseAmount
) external;

Transfers amount of bonded tokens from from to to, optionally releasing fromReleaseAmount from a hold first. Does not change the total supply of bonded tokens.

---

agentWithdrawFromBonded

function agentWithdrawFromBonded(
    uint64 policyID,
    address from,
    address to,
    uint256 amount,
    uint256 fromReleaseAmount
) external;

Transfers amount of underlying assets from a bonded position directly to the to address by first converting the appropriate number of shares. Optionally releases fromReleaseAmount from a hold first.

---

agentExecuteWithSponsor

function agentExecuteWithSponsor(
    uint64 policyID,
    address payor,
    address recipient,
    uint256 msgValue,
    uint256 gasLimit,
    address callTarget,
    bytes calldata callData
) external payable
  returns (
    uint128 actualPayorCost,
    bool success,
    bytes memory returnData
  );

Executes a call to callTarget with callData, sponsored by the payor’s bonded balance in a particular policy. The recipient receives the cost charged to the payor’s bonded balance. Returns the actual cost paid, whether the call succeeded, and any returned data.

Parameters

Name	Type	Description
policyID	uint64	Policy under which the payor's bonded balance is debited
payor	address	Address whose bonded balance will sponsor the gas cost
recipient	address	Address receiving the sponsored cost
msgValue	uint256	Amount of Ether (or native token) passed along to the inner call, combined with any additional funds from msg.value
gasLimit	uint256	Gas limit to be used for the inner call
callTarget	address	Address of the contract to call
callData	bytes	Calldata to pass to callTarget

Returns

Name	Type	Description
actualPayorCost	uint128	Final amount of bonded tokens spent by the payor
success	bool	Indicates whether the inner call succeeded
returnData	bytes	Data returned by the inner call

---