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.