PP_Streaming_v1.sol
Inherits: Module_v1, IPP_Streaming_v1
Author: Inverter Network
Manages continuous and linear streaming payment streams within the Inverter Network, allowing multiple concurrent streams per recipient. Provides tools to claim streamed amounts and manage payment schedules dynamically.
Supports complex payment interactions including streaming based on time for multiple clients and recipients, integrated with error handling for payments and managing active streaming schedules and their cancellations. DISCLAIMER: Known Limitations This contract has a known limitation that could potentially lead to a Denial of Service (DoS) attack. The activePaymentReceivers array for a client can grow unbounded, which may cause gas-intensive operations to exceed block gas limits under certain conditions. This could temporarily render some functions inoperable. While this limitation does not directly risk user funds, it may temporarily prevent users from staking, unstaking, or claiming rewards if exploited. The development team is aware of this issue and may implement a fix in future upgrades if necessary. CAUTION: Workflow deployers should be especially careful when using this payment processor with contracts that allow users to directly initiate payment streams. Such setups are particularly vulnerable to this limitation and could more easily trigger a DoS condition.
State Variables
numStreams
Provides a unique id for new payment orders added for a specific client & paymentReceiver combo. paymentClient => paymentReceiver => streamId(uint).
mapping(address => mapping(address => uint)) public numStreams;streams
Tracks all stream details for all payment orders of a paymentReceiver for a specific paymentClient. paymentClient => paymentReceiver => streamId => Wallet.
mapping(address => mapping(address => mapping(uint => Stream))) private streams;unclaimableStreams
Tracks all streams for payments that could not be made to the paymentReceiver due to any reason. paymentClient => token address => paymentReceiver => streamId array.
mapping(address => mapping(address => mapping(address => uint[]))) internal
unclaimableStreams;unclaimableAmountsForStream
Tracks all payments that could not be made to the paymentReceiver due to any reason. paymentClient => token address => paymentReceiver => streamId => unclaimable Amount.
mapping(
address => mapping(address => mapping(address => mapping(uint => uint)))
) internal unclaimableAmountsForStream;activePaymentReceivers
List of addresses with open payment Orders per paymentClient. paymentClient => listOfPaymentReceivers(address[]). Duplicates are not allowed.
mapping(address => address[]) private activePaymentReceivers;activeStreams
List of streamIds of all payment orders of a particular paymentReceiver for a particular paymentClient. client => paymentReceiver => arrayOfStreamIdsWithPendingPayment(uint[]).
mapping(address => mapping(address => uint[])) private activeStreams;defaultStart
Default start, cliff and end times for new payment orders.
uint private defaultStart;defaultCliff
uint private defaultCliff;defaultEnd
uint private defaultEnd;__gap
Storage gap for future upgrades.
uint[47] private __gap;Functions
supportsInterface
See {IERC165-supportsInterface}.
function supportsInterface(bytes4 interfaceId)
public
view
virtual
override(Module_v1)
returns (bool);onlyModule
Checks that the caller is an active module.
modifier onlyModule();validClient
Checks that the client is calling for itself.
modifier validClient(address client);activePaymentReceiver
Checks that the paymentReceiver is an active paymentReceiver.
modifier activePaymentReceiver(address client, address paymentReceiver);init
function init(
IOrchestrator_v1 orchestrator_,
Metadata memory metadata,
bytes memory configData
) external override(Module_v1) initializer;claimAll
claim everything that the paymentClient owes to the _msgSender till the current timestamp.
This function should be callable if the _msgSender is an activePaymentReceiver.
function claimAll(address client) external;Parameters
client
address
The {IERC20PaymentClientBase_v1} instance address that processes all claims from _msgSender.
claimPreviouslyUnclaimable
claim every unclaimable amount that the paymentClient owes to the _msgSender and send it to a specified receiver.
This function should be callable if the _msgSender has unclaimedAmounts.
function claimPreviouslyUnclaimable(
address client,
address token,
address receiver
) external;Parameters
client
address
The IERC20PaymentClientBase_v1 instance address that processes all claims from _msgSender.
token
address
address of the payment token.
receiver
address
The address that will receive the previously unclaimable amount.
claimForSpecificStream
claim the total amount up til block.timestamp from the client for a payment order with id = streamId by _msgSender.
If for a specific streamId, the tokens could not be transferred for some reason, it will added to the unclaimableAmounts of the paymentReceiver, and the amount would no longer hold any co-relation with he specific streamId of the paymentReceiver.
function claimForSpecificStream(address client, uint streamId) external;Parameters
client
address
The {IERC20PaymentClientBase_v1} instance address that processes the streamId claim from _msgSender.
streamId
uint256
The ID of the streaming payment order for which claim is being made.
processPayments
Processes all payments from an {IERC20PaymentClientBase_v1} instance. Please note: this function does not support callbacks on transfer of tokens.
It's up to the the implementation to keep up with what has been paid out or not.
function processPayments(IERC20PaymentClientBase_v1 client)
external
onlyModule
validClient(address(client));Parameters
client
IERC20PaymentClientBase_v1
The {IERC20PaymentClientBase_v1} instance to process its to payments.
cancelRunningPayments
Cancels all unfinished payments from an {IERC20PaymentClientBase_v1} instance.
It's up to the the implementation to keep up with what has been paid out or not.
function cancelRunningPayments(IERC20PaymentClientBase_v1 client)
external
onlyModule
validClient(address(client));Parameters
client
IERC20PaymentClientBase_v1
The {IERC20PaymentClientBase_v1} instance to process its to payments.
removeAllPaymentReceiverPayments
Deletes all payments related to a paymentReceiver & leaves currently streaming tokens in the {IERC20PaymentClientBase_v1}.
this function calls _removePayment which goes through all the payment orders for a paymentReceiver. For the payment orders that are completely streamed, their details are deleted in the _claimForSpecificStrea function and for others it is deleted in the _removePayment function only, leaving the currently streaming tokens as balance of the paymentClient itself.
function removeAllPaymentReceiverPayments(
address client,
address paymentReceiver
) external onlyOrchestratorAdmin;Parameters
client
address
The {IERC20PaymentClientBase_v1} instance address from which we will remove the payments.
paymentReceiver
address
PaymentReceiver's address.
removePaymentForSpecificStream
Deletes a specific payment with id = streamId for a paymentReceiver & leaves currently streaming tokens in the {IERC20PaymentClientBase_v1}.
the detail of the wallet that is being removed is either deleted in the _claimForSpecificStream or later down in this function itself depending on the timestamp of when this function was called.
function removePaymentForSpecificStream(
address client,
address paymentReceiver,
uint streamId
) external onlyOrchestratorAdmin;Parameters
client
address
The {IERC20PaymentClientBase_v1} instance address from which we will remove the payment.
paymentReceiver
address
Address of the paymentReceiver whose payment order is to be removed.
streamId
uint256
The ID of the paymentReceiver's payment order which is to be removed.
isActivePaymentReceiver
Tells whether a paymentReceiver has any pending payments for a particular client.
This function is for convenience and can be easily figured out by other means in the codebase.
function isActivePaymentReceiver(address client, address paymentReceiver)
public
view
returns (bool);Parameters
client
address
Address of the payment client.
paymentReceiver
address
Address of the paymentReceiver.
Returns
<none>
bool
true if the paymentReceiver is active for the payment client.
startForSpecificStream
Getter for the start timestamp of a particular payment order with id = streamId associated with a particular paymentReceiver.
function startForSpecificStream(
address client,
address paymentReceiver,
uint streamId
) public view returns (uint);Parameters
client
address
address of the payment client.
paymentReceiver
address
PaymentReceiver's address.
streamId
uint256
Id of the wallet for which start is fetched.
Returns
<none>
uint256
start timestamp of the payment order.
cliffForSpecificStream
Getter for the cliff duration of a particular payment order with id = streamId associated with a particular paymentReceiver.
function cliffForSpecificStream(
address client,
address paymentReceiver,
uint streamId
) public view returns (uint);Parameters
client
address
address of the payment client.
paymentReceiver
address
PaymentReceiver's address.
streamId
uint256
Id of the wallet for which cliff is fetched.
Returns
<none>
uint256
cliff duration of the payment order.
endForSpecificStream
Getter for the stream end timestamp of a particular payment order with id = streamId associated with a particular paymentReceiver.
function endForSpecificStream(
address client,
address paymentReceiver,
uint streamId
) public view returns (uint);Parameters
client
address
address of the payment client.
paymentReceiver
address
PaymentReceiver's address.
streamId
uint256
Id of the wallet for which end is fetched.
Returns
<none>
uint256
end timestamp of the payment order.
releasedForSpecificStream
Getter for the amount of tokens already released for a particular payment order with id = streamId associated with a particular paymentReceiver.
function releasedForSpecificStream(
address client,
address paymentReceiver,
uint streamId
) public view returns (uint);Parameters
client
address
address of the payment client.
paymentReceiver
address
PaymentReceiver's address.
streamId
uint256
Id of the wallet for which released is fetched.
Returns
<none>
uint256
released amount of the payment order.
streamedAmountForSpecificStream
Calculates the amount of tokens that has already streamed for a particular payment order with id = streamId associated with a particular paymentReceiver.
function streamedAmountForSpecificStream(
address client,
address paymentReceiver,
uint streamId,
uint timestamp
) public view returns (uint);Parameters
client
address
paymentReceiver
address
PaymentReceiver's address.
streamId
uint256
Id of the wallet for which the streamed amount is fetched.
timestamp
uint256
the time upto which we want the streamed amount.
Returns
<none>
uint256
streamed amount of the stream with id = streamId.
releasableForSpecificStream
Getter for the amount of releasable tokens for a particular payment order with id = streamId associated with a particular paymentReceiver.
function releasableForSpecificStream(
address client,
address paymentReceiver,
uint streamId
) public view returns (uint);Parameters
client
address
paymentReceiver
address
PaymentReceiver's address.
streamId
uint256
Id of the wallet for which the releasable amount is fetched.
Returns
<none>
uint256
releasable amount of the stream with id = streamId.
unclaimable
Getter for the amount of tokens that could not be claimed.
function unclaimable(address client, address token, address paymentReceiver)
public
view
returns (uint amount);Parameters
client
address
address of the payment client.
token
address
address of the payment token.
paymentReceiver
address
PaymentReceiver's address.
Returns
amount
uint256
Amount of tokens that could not be claimed.
viewAllPaymentOrders
See all active payment orders for a paymentClient associated with a particular paymentReceiver.
the paymentReceiver must be an active paymentReceiver for the particular payment client.
function viewAllPaymentOrders(address client, address paymentReceiver)
external
view
activePaymentReceiver(client, paymentReceiver)
returns (Stream[] memory);Parameters
client
address
Address of the payment client.
paymentReceiver
address
Address of the paymentReceiver.
Returns
<none>
Stream[]
all streams for a particular payment client and payment receiver.
validPaymentOrder
Function that checks if the given PaymentOrder was valid.
function validPaymentOrder(IERC20PaymentClientBase_v1.PaymentOrder memory order)
external
returns (bool);Parameters
order
IERC20PaymentClientBase_v1.PaymentOrder
The IERC20PaymentClientBase_v1 Order that needs to be checked.
Returns
<none>
bool
valid Bool if the Payment Order is valid.
setStreamingDefaults
function setStreamingDefaults(uint newStart_, uint newCliff_, uint newEnd_)
external
onlyOrchestratorAdmin;getStreamingDefaults
function getStreamingDefaults() public view returns (uint, uint, uint);_afterClaimCleanup
Common set of steps to be taken after everything has been claimed from a specific stream.
function _afterClaimCleanup(
address client,
address paymentReceiver,
uint streamId
) internal;Parameters
client
address
Address of the payment client.
paymentReceiver
address
Address of the paymentReceiver.
streamId
uint256
ID of the stream that was fully claimed.
_findAddressInActiveStreams
used to find whether a particular paymentReceiver has pending payments with a client.
This function returns the first instance of the paymentReceiver address in the activePaymentReceivers[client] array, but that is completely fine as the array does not allow duplicates.
function _findAddressInActiveStreams(address client, address paymentReceiver)
internal
view
returns (uint);Parameters
client
address
address of the payment client.
paymentReceiver
address
address of the paymentReceiver.
Returns
<none>
uint256
uint The index of the paymentReceiver in the activePaymentReceivers[client] array. Returns type(uint256).max otherwise.
_findActiveStream
Used to find whether a particular payment order associated with a paymentReceiver and paymentClient with id = streamId is active or not.
Active means that the particular payment order is still to be paid out/claimed. This function returns the first instance of the streamId in the activeStreams[client][paymentReceiver] array, but that is fine as the array does not allow duplicates.
function _findActiveStream(
address client,
address paymentReceiver,
uint streamId
) internal view returns (uint);Parameters
client
address
Address of the payment client.
paymentReceiver
address
Address of the paymentReceiver.
streamId
uint256
ID of the payment order that needs to be searched.
Returns
<none>
uint256
uint The index of the paymentReceiver in the activeStreams[client][paymentReceiver] array. Returns type(uint256).max otherwise.
_cancelRunningOrders
Used to cancel all unfinished payments from the client.
All active payment orders of all active paymentReceivers associated with the client, are iterated through and their details are deleted.
function _cancelRunningOrders(address client) internal;Parameters
client
address
address of the payment client.
_removePayment
Deletes all payments related to a paymentReceiver & leaves currently streaming tokens in the {IERC20PaymentClientBase_v1}.
This function calls _removePayment which goes through all the payment orders for a paymentReceiver. For the payment orders that are completely streamed, their details are deleted in the _claimForSpecificStream function and for others it is deleted in the _removePayment function only, leaving the currently streaming tokens as balance of the paymentClient itself.
function _removePayment(address client, address paymentReceiver) internal;Parameters
client
address
Address of the payment client.
paymentReceiver
address
Address of the paymentReceiver.
_removePaymentForSpecificStream
Used to remove the payment order with id = streamId from the `activeStreams[client][paymentReceiver] array.
This function simply removes a particular payment order from the earlier mentioned array. The implications of removing a payment order from this array have to be handled outside of this function, such as checking whether the `paymentReceiver is still active or not, etc.
function _removePaymentForSpecificStream(
address client,
address paymentReceiver,
uint streamId
) internal;Parameters
client
address
Address of the payment client.
paymentReceiver
address
Address of the paymentReceiver.
streamId
uint256
Id of the payment order that needs to be removed.
_removeStreamInformationForSpecificStream
Used to remove the stream info of the payment order with id = streamId.
This function simply removes the stream details of a particular payment order. The implications of removing the stream info of payment order have to be handled outside of this function.
function _removeStreamInformationForSpecificStream(
address client,
address paymentReceiver,
uint streamId
) internal;Parameters
client
address
Address of the payment client.
paymentReceiver
address
Address of the paymentReceiver.
streamId
uint256
Id of the payment order whose stream information needs to be removed.
_removePaymentReceiverFromActiveStreams
Used to remove a paymentReceiver as one of the beneficiaries of the payment client
This function will be called when all the payment orders of a payment client associated with a particular paymentReceiver has been fulfilled. Also signals that the paymentReceiver is no longer an active paymentReceiver according to the payment client.
function _removePaymentReceiverFromActiveStreams(
address client,
address paymentReceiver
) internal;Parameters
client
address
Address of the payment client.
paymentReceiver
address
Address of the paymentReceiver.
_addPayment
Adds a new payment containing the details of the monetary flow depending on the module.
This function can handle multiple payment orders associated with a particular paymentReceiver for the same payment client without overriding the earlier ones. The maximum payment orders for a paymentReceiver MUST BE capped at (2**256-1).
function _addPayment(
address _client,
IERC20PaymentClientBase_v1.PaymentOrder memory _order,
uint _streamId
) internal;Parameters
_client
address
PaymentReceiver's address.
_order
IERC20PaymentClientBase_v1.PaymentOrder
PaymentOrder that needs to be added.
_streamId
uint256
ID of the new stream of the a particular paymentReceiver being added.
_claimAll
Used to claim all the payment orders associated with a particular paymentReceiver for a given payment client.
Calls the _claimForSpecificStream function for all the active streams of a particular paymentReceiver for the given payment client. Depending on the time this function is called, the steamed payments are transferred to the paymentReceiver. For payment orders that are fully steamed, their details are deleted and changes are made to the state of the contract accordingly.
function _claimAll(address client, address paymentReceiver) internal;Parameters
client
address
Address of the payment client.
paymentReceiver
address
Address of the paymentReceiver for which every payment order will be claimed.
_claimForSpecificStream
Used to claim the payment order of a particular paymentReceiver for a given payment client with id = streamId.
Depending on the time this function is called, the steamed payments are transferred to the paymentReceiver or accounted in unclaimableAmounts. For payment orders that are fully steamed, their details are deleted and changes are made to the state of the contract accordingly.
function _claimForSpecificStream(
address client,
address paymentReceiver,
uint streamId
) internal;Parameters
client
address
Address of the payment client.
paymentReceiver
address
Address of the paymentReceiver for which every payment order will be claimed.
streamId
uint256
ID of the payment order that is to be claimed.
_claimPreviouslyUnclaimable
Used to claim the unclaimable amount of a particular paymentReceiver for a given payment client.
Assumes that the streamId array is not empty.
function _claimPreviouslyUnclaimable(
address client,
address token,
address paymentReceiver
) internal;Parameters
client
address
Address of the payment client.
token
address
paymentReceiver
address
Address of the paymentReceiver for which the unclaimable amount will be claimed.
_streamAmountForSpecificStream
Virtual implementation of the stream formula. Returns the amount steamed, as a function of time, for an asset given its total historical allocation.
function _streamAmountForSpecificStream(
address client,
address paymentReceiver,
uint streamId,
uint timestamp
) internal view virtual returns (uint);Parameters
client
address
paymentReceiver
address
The paymentReceiver to check on.
streamId
uint256
ID of a particular paymentReceiver's stream whose stream schedule needs to be checked.
timestamp
uint256
The time upto which we want the steamed amount.
_validPaymentReceiver
Validate address input.
function _validPaymentReceiver(address addr) internal view returns (bool);Parameters
addr
address
Address to validate.
Returns
<none>
bool
True if address is valid.
_validTotal
Validate uint total amount input.
function _validTotal(uint _total) internal pure returns (bool);Parameters
_total
uint256
uint to validate.
Returns
<none>
bool
True if uint is valid.
_validTimes
Validate uint start input.
function _validTimes(uint _start, uint _cliff, uint _end)
internal
pure
returns (bool);Parameters
_start
uint256
uint to validate.
_cliff
uint256
uint to validate.
_end
uint256
uint to validate.
Returns
<none>
bool
True if uint is valid.
_validPaymentToken
Validate payment token input.
function _validPaymentToken(address _token) internal returns (bool);Parameters
_token
address
Address of the token to validate.
Returns
<none>
bool
True if address is valid.
_validOriginAndTargetChain
function _validOriginAndTargetChain(uint originChainId_, uint targetChainId_)
internal
view
returns (bool);_getStreamingDetails
function _getStreamingDetails(bytes32 flags, bytes32[] memory data)
internal
view
returns (uint start, uint cliff, uint end);_setDefaultTimes
Sets the default start time, cliff and end times for new payment orders.
function _setDefaultTimes(uint newStart_, uint newCliff_, uint newEnd_)
internal;Parameters
newStart_
uint256
The new default start time.
newCliff_
uint256
The new default cliff duration.
newEnd_
uint256
The new default end time.
Last updated