Stream and Sub

Stream Contract Documentation

The Stream contract is a Solidity smart contract designed to facilitate token streaming between parties over a specified time window. It allows a streamer to authorize and manage token streams to recipients, supporting batch operations and providing utility functions for stream management.

Overview

The Stream contract enables token streaming, allowing a streamer to authorize a continuous transfer of tokens to a recipient over a specified period (window). The contract handles the calculation of allowable amounts based on elapsed time and supports one-time or recurring streams. It also includes mechanisms for batch operations and stream cancellation.

Key Components

Libraries and Interfaces

  • IERC20: A custom interface extending the standard ERC20 interface with additional functions (name, symbol, decimals) for token details.

  • SafeERC20: A library providing safe wrappers around ERC20 operations, ensuring that token transfers and approvals are handled securely.

Data Structures

  • StreamDetails: A struct containing information about each stream:

    • address streamer: The address initiating the stream.

    • address recipient: The address receiving the streamed tokens.

    • address token: The ERC20 token being streamed.

    • uint256 totalStreamed: The total amount streamed so far.

    • uint256 outstanding: The remaining amount to be streamed.

    • uint256 allowable: The total allowable amount for the stream.

    • uint256 window: The time window over which the tokens are streamed.

    • uint256 timestamp: The last interaction timestamp.

    • bool once: Indicates if the stream is a one-time transfer.

Events

  • StreamAllowed: Emitted when a stream is authorized.

    solidityCopy codeevent StreamAllowed(
    address indexed streamer,
    address indexed token,
    address indexed recipient,
    uint256 amount
);

  • Streamed: Emitted when tokens are successfully streamed.

    solidityCopy codeevent Streamed(
    address indexed token,
    address indexed streamer,
    address indexed recipient,
    uint256 amount
);

  • StreamFailure: Emitted when a streaming attempt fails.

    solidityCopy codeevent StreamFailure(
    address indexed token,
    address indexed streamer,
    address indexed recipient,
    string message
);

Contract Variables

  • mapping(bytes32 => StreamDetails) public streamDetails;

    • Stores the details of each stream identified by a unique hash.

  • mapping(address => bytes32[]) public streamDetailsByStreamer;

    • Keeps track of stream hashes authorized by each streamer.

  • mapping(address => bytes32[]) public streamDetailsByRecipient;

    • Keeps track of stream hashes associated with each recipient.

  • address payable public feeAddress;

    • The address where fees are collected.

  • uint public fee;

    • The fee percentage (in basis points) charged per stream.

Functions

Constructor

constructor(address payable feeAddrs)

  • Initializes the contract with the fee collection address.

  • Parameters:

    • feeAddrs: The address where streaming fees will be sent.

Streaming Functions

allowStream

function allowStream(
    address token,
    address recipient,
    uint256 amount,
    uint256 window,
    bool once
) public

  • Authorizes a new token stream or updates an existing one.

  • Parameters:

    • token: The ERC20 token to be streamed.

    • recipient: The address receiving the tokens.

    • amount: The total amount to be streamed.

    • window: The time window for streaming.

    • once: If true, the stream is a one-time transfer.

stream

solidityCopy codefunction stream(address token, address streamer, address recipient) public

  • Executes the streaming of allowable tokens from the streamer to the recipient.

  • Parameters:

    • token: The ERC20 token being streamed.

    • streamer: The address initiating the stream.

    • recipient: The address receiving the tokens.

batchStreamAvailable

solidityCopy codefunction batchStreamAvailable(
    address[] memory tokens,
    address[] memory streamers,
    address[] memory recipients
) public

  • Executes streaming for multiple streams where tokens are available.

  • Parameters:

    • tokens: Array of ERC20 tokens.

    • streamers: Array of streamer addresses.

    • recipients: Array of recipient addresses.

Batch Operations

batchAllowStream

solidityCopy codefunction batchAllowStream(
    address[] calldata tokens,
    address[] calldata recipients,
    uint256[] calldata amounts,
    uint256[] calldata windows,
    bool[] calldata onces
) external

  • Authorizes multiple streams in a single transaction.

  • Parameters:

    • tokens, recipients, amounts, windows, onces: Arrays corresponding to the allowStream parameters.

batchStream

solidityCopy codefunction batchStream(
    address[] calldata tokens,
    address[] calldata streamers,
    address[] calldata recipients
) external

  • Executes multiple streams in a single transaction.

  • Parameters:

    • tokens, streamers, recipients: Arrays corresponding to the stream parameters.

batchComputeHash

solidityCopy codefunction batchComputeHash(
    address[] calldata streamers,
    address[] calldata tokens,
    address[] calldata recipients
) public pure returns (bytes32[] memory)

  • Computes hashes for multiple streams.

  • Parameters:

    • streamers, tokens, recipients: Arrays of stream details.

  • Returns:

    • An array of computed hashes.

Stream Management

cancelStreams

solidityCopy codefunction cancelStreams(
    address[] calldata tokens,
    address[] calldata streamers,
    address[] calldata recipients
) external

  • Cancels specified streams.

  • Parameters:

    • tokens, streamers, recipients: Arrays corresponding to the streams to be canceled.

  • Access Control:

    • Only the streamer or recipient can cancel a stream.

setFee

solidityCopy codefunction setFee(uint _fee, address newFeeAddress) public

  • Updates the streaming fee and fee collection address.

  • Parameters:

    • _fee: New fee percentage (max 5%).

    • newFeeAddress: New address for fee collection.

  • Access Control:

    • Only callable by the current feeAddress.

Utility Functions

computeHash

solidityCopy codefunction computeHash(
    address streamer,
    address token,
    address recipient
) public pure returns (bytes32)

  • Generates a unique hash for a stream.

  • Parameters:

    • streamer, token, recipient: Stream details.

  • Returns:

    • A unique bytes32 hash.

getAvailable

solidityCopy codefunction getAvailable(
    address token,
    address streamer,
    address recipient
) public view returns (uint256)

  • Calculates the available amount for streaming based on elapsed time.

  • Parameters:

    • token, streamer, recipient: Stream details.

  • Returns:

    • The allowable amount available for streaming.

getStreamDetails

solidityCopy codefunction getStreamDetails(
    bytes32[] calldata hashes
) public view returns (
    uint[] memory availableAmounts,
    uint8[] memory decimals,
    string[] memory tokenNames,
    string[] memory tokenSymbols,
    StreamDetails[] memory details
)

  • Retrieves detailed information for multiple streams.

  • Parameters:

    • hashes: Array of stream hashes.

  • Returns:

    • availableAmounts: Amounts available for streaming.

    • decimals, tokenNames, tokenSymbols: Token metadata.

    • details: Array of StreamDetails.

getStreamable

solidityCopy codefunction getStreamable(
    bytes32[] calldata hashes
) public view returns (bool[] memory canStream, uint[] memory balances, uint[] memory allowances)

  • Checks if streams are executable based on balances and allowances.

  • Parameters:

    • hashes: Array of stream hashes.

  • Returns:

    • canStream: Boolean array indicating if streaming is possible.

    • balances: Streamer token balances.

    • allowances: Allowances granted to the contract.

viewStreamerAllowances

solidityCopy codefunction viewStreamerAllowances(
    address streamer
) public view returns (bytes32[] memory)

  • Retrieves all stream hashes authorized by a streamer.

  • Parameters:

    • streamer: The address of the streamer.

  • Returns:

    • An array of stream hashes.

viewRecipientAllowances

solidityCopy codefunction viewRecipientAllowances(
    address recipient
) public view returns (bytes32[] memory)

  • Retrieves all stream hashes associated with a recipient.

  • Parameters:

    • recipient: The address of the recipient.

  • Returns:

    • An array of stream hashes.

Usage Examples

Authorize a New Stream

solidityCopy codestreamContract.allowStream(
    tokenAddress,
    recipientAddress,
    totalAmount,
    timeWindow,
    isOneTime
);

  • Parameters:

    • tokenAddress: The ERC20 token contract address.

    • recipientAddress: The recipient's address.

    • totalAmount: Total tokens to be streamed.

    • timeWindow: Duration over which tokens are streamed.

    • isOneTime: Set to true for a one-time stream.

Execute a Stream

solidityCopy codestreamContract.stream(
    tokenAddress,
    streamerAddress,
    recipientAddress
);

  • Note: This function can be called by anyone, but it will only execute if the streaming conditions are met.

Cancel a Stream

solidityCopy codestreamContract.cancelStreams(
    [tokenAddress],
    [streamerAddress],
    [recipientAddress]
);

  • Note: Only the streamer or recipient can cancel a stream.

Batch Streaming

solidityCopy codestreamContract.batchStream(
    tokenAddressesArray,
    streamerAddressesArray,
    recipientAddressesArray
);

  • Purpose: Executes multiple streams in a single transaction.

Important Notes

  • Fees: A fee (up to 5%) can be set by the feeAddress and is deducted from each streamed amount.

  • Access Control: Certain functions are restricted to specific roles (e.g., only the streamer or recipient can cancel a stream).

  • Error Handling: The contract emits StreamFailure events when streaming attempts fail, providing the reason for failure.

  • SafeERC20 Usage: The contract uses the SafeERC20 library to handle token transfers securely.

PreviousContractsNextVault

Last updated