Push Core Contract

The Push core protocol, as the name might indicate, is the main smart contract as it handles some of the most crucial features like Channel creation, governance, channel state changes as well as funds and incentive mechanisms, etc.

important

Push Core smart contract is only be deployed on the Ethereum blockchain and not on any other chain.

Types & Modifiers

Explains the different types of Data types and access controls used in the Push core smart contract

Storage Variables

  string public constant name = "EPNS_CORE_V1.5";
  address public pushChannelAdmin;
  address public governance;
  address public daiAddress;
  address public aDaiAddress;
  address public WETH_ADDRESS;
  address public epnsCommunicator;
  address public UNISWAP_V2_ROUTER;
  address public PUSH_TOKEN_ADDRESS;
  address public lendingPoolProviderAddress;

  uint256 public REFERRAL_CODE;
  uint256 ADJUST_FOR_FLOAT;
  uint256 public channelsCount;

  //  @notice Helper Variables for FSRatio Calculation | GROUPS = CHANNELS
  uint256 public groupNormalizedWeight;
  uint256 public groupHistoricalZ;
  uint256 public groupLastUpdate;
  uint256 public groupFairShareCount;

  // @notice Necessary variables for Keeping track of Funds and Fees
  uint256 public CHANNEL_POOL_FUNDS;
  uint256 public PROTOCOL_POOL_FEES;
  uint256 public ADD_CHANNEL_MIN_FEES;
  uint256 public FEE_AMOUNT;
  uint256 public MIN_POOL_CONTRIBUTION;

To keep track of FUNDS and FEES in Push Core

CHANNEL_POOL_FUNDS

Keeps track of the PUSH tokens that are claimable to the channel owners whenever they deactivate or delete the channel.
The amount of PUSH token added to this variable is the remaining amount after deducting the PROTOCOL_POOL_FEES from the amount that a user sends while creating or reactivating a channel.
For example, you sent 50 tokens to create a channel, then 10 tokens will be added to PROTOCOL_POOL_FEES, and the remaining 40 is added to CHANNEL_POOL_FUNDS.

PROTOCOL_POOL_FEES

A small fee amount is deducted by the core smart contract for any imperative transaction like channel creation, channel reactivation, channel detail modification, and others.
As of now, the protocol fee is set to be equal to 10 PUSH tokens. This value, however, can be changed by the community later using on-chain governance.
Simply deducted from the same amount that a channel creator chooses to stake in the protocol. For example, if you chose to stake 50 PUSH during channel creation, 10 of those 50 PUSH tokens go into Protocol Fee Pool, while the remaining goes into Channel Pool Funds that are claimable by channel owners anytime they choose to deactivate their channel.

ADD_CHANNEL_MIN_FEES

The minimum amount of PUSH that is required for creating or reactivating a channel.
The current value of this state variable is 50 PUSH.
Can be updated only via on-chain governance using the setMinChannelCreationFees() function.
Can never be below 50 PUSH.

FEE_AMOUNT

Represents the deactivation fee charged to a channel owner when the channel is Deactivated.
The current value of this state variable is 10 PUSH.
Can be updated only via on-chain governance using the setFeeAmount() function.

MIN_POOL_CONTRIBUTION

Represents the constant value of 1 PUSH used for the calculation of a channel's weight in the protocol.
This amount is deducted from the channel pool contribution at the time of deactivating a channel and the remaining amount is refunded to the user.

Storage variables for FSRatio Calculation

The concept of adjusting the fair share of channels is no longer being used by the protocol, That’s why these variables have no significance from version 1.5 onwards.
These variables are only present in the contract to avoid storage collisions, as our contracts are upgradeable.
Below are the uses of these variables in version 1. No longer needed in Version 1.5

Structs

struct Channel {
  ChannelType channelType;
  uint8 channelState;

  address verifiedBy;

  uint256 poolContribution;
  uint256 channelHistoricalZ;
  uint256 channelFairShareCount;

  uint256 channelLastUpdate;
  uint256 channelStartBlock;
  uint256 channelUpdateBlock;

  uint256 channelWeight;
  uint256 expiryTime;
}

The Channel struct in the Push Core smart contract stores every crucial data about the channels that are created on the core contract.

ChannelType

Denotes the type of channel being created.
A Channel can be any of the 6 available types —
1. ProtocolNonInterest
2. ProtocolPromotion
3. InterestBearingOpen
4. InterestBearingMutual
5. Timebound
6. TokenGaited

channelState

Symbolizes the current state of a particular channel.
A channel can have any of the following states —
1. INACTIVE - 0
2. ACTIVE - 1
3. DEACTIVATED - 2
4. BLOCKED - 3

verifiedBy

Denotes the address of the verifier of the Channel

poolContribution

Denotes the total amount of PUSH deposited by the channel owner during Channel Creation.
Pool contribution is calculated by deducting the FEE_AMOUNT from the amount user sends at the time of channel creation or reactivation.

channelLastUpdate

The last update block number. It was used to calculate the fair share ratio, but now it just stores the last update block number

channelStartBlock

Represents the block number when a specific channel was created

channelUpdateBlock

Represents the block number that depicts when a channel was updated

channelWeight

Represents the individual weight to be applied as per pool contribution.

expiryTime

The timestamp at which the channel gets expired and can be deleted by the owner

Modifiers

onlyPushChannelAdmin()

Only allows Push Channel Admin to access the function

onlyGovernance()

Only allows Governance contract to access the function

onlyInactiveChannels()

Only for channels that are currently in an INACTIVE state
Used in the following function:
createChannelWithFees()

onlyActivatedChannels()

Only for channels that are currently in an ACTIVE state
Used in the following functions:
createChannelSettings()
deactivateChannel()
verifyChannel()

onlyDeactivatedChannels()

Only for channels that are neither in BLOCKED state nor INACTIVE
Used in the following function:
reactivateChannel()

onlyUnblockedChannels()

Only for channels that are currently in a BLOCKED state
Used in the following function:
blockChannel()

onlyChannelOwner()

Only for the owner of a particular channel
Used in the following function:
updateChannelMeta()

onlyUserAllowedChannelType()

Ensures that the channel type passed as an argument while creating a channel is a valid channel type
Used in the following function:
createChannelWithFees()

Mappings

channels

mapping(address => Channel) public channels;
Maps a channel's address to its Struct

channelById

mapping(uint256 => address) public channelById;
Maps the uint256 ID of a particular channel to its address.
Updated in the _createChannel() function.

channelNotifSettings

mapping(address => string) public channelNotifSettings;
Keeps track of the notification settings selected by a channel
Updated in the createChannelSettings() function.

nonces

mapping(address => uint256) public nonces;
Used to keep track of how many times a user signed a message.
Used in off-chain signature verification.
increments every time a user signs a message

channelUpdateCounter

mapping(address => uint256) public channelUpdateCounter;
Tracks the update count of a channel, i.e. how many times a channel is being updated.
Used to determine the price of updating a channel. More the update count more the price.

usersRewardsClaimed

mapping(address => uint256) public usersRewardsClaimed;
tracks the rewards a user has claimed.
not implemented in V1.5 but will be implemented in V2

Enums

The EPNS Core smart contract includes 2 main ENUMS.

ChannelType

enum ChannelType {
  ProtocolNonInterest,
  ProtocolPromotion,
  InterestBearingOpen,
  InterestBearingMutual,
  Timebound,
  TokenGaited
}

This represents the type of channel being created. It can be any one of the 6 types —
1. ProtocolNonInterest,
2. ProtocolPromotion,
3. InterestBearingOpen,
4. InterestBearingMutual,
5. Timebound,
6. TokenGaited

ChannelAction

enum ChannelAction {
   ChannelRemoved,
   ChannelAdded,
   ChannelUpdated
}

This enum has no use in V1.5 as this was mainly used while calculating the fair share of channels. This is only present in V1.5 to avoid storage collisions.
It was used to represent the different channel actions that occur in the protocol.
There could be 3 main channel actions:
ChannelAdded: When a channel is created and added to the protocol
ChannelRemoved: When a channel is blocked and removed from the protocol
ChannelUpdated: When a channel is either deactivated or reactivated

Interface

Push contract interacts with PUSH token and communicator contract with the help of these interfaces

interface IPUSH {
  function born() external view returns(uint);
  function totalSupply() external view returns(uint);
  function resetHolderWeight(address holder) external;
  function returnHolderUnits(address account, uint atBlock) external view returns (uint);
}

interface IEPNSCommV1 {
  function subscribeViaCore(address _channel, address _user) external returns(bool);
  function unSubscribeViaCore(address _channel, address _user) external returns (bool);
}

Methods

Brief overview of all the imperative functionalities of the Push Core smart contract version 1.5.

Only Admin Setter Functions

1. setEpnsCommunicatorAddress

function setEpnsCommunicatorAddress(address _commAddress) external onlyPushChannelAdmin() {};

Description:
Allows only the Push Channel Admin to set the Push Communicator smart contract's address.

Arguments:

Argument	Type	Description
_commAddress	address	Address of the communicator protocol

2. setGovernanceAddress

function setGovernanceAddress(address _governanceAddress) external onlyPushChannelAdmin() {};

Description:
Allows only the Push Channel Admin to set the Governance address.

Arguments:

Argument	Type	Description
_governanceAddress	address	Address of the Governance protocol

3. setFeeAmount

function setFeeAmount(uint256 _newFees) external onlyGovernance() {};

Description:
Sets the FEE_AMOUNT to a new fee amount.

Arguments:

Argument	Type	Description
_newFees	uint256	New Fee Amount in the protocol

4. setMinChannelCreationFees

function setMinChannelCreationFees(uint256 _newFees) external onlyGovernance() {};

Description:
Sets the Channel Creation fees to a new fee amount.

Arguments:

Argument	Type	Description
_newFees	uint256	New Channel Creation fees in the protocol

5. transferPushChannelAdminControl

function transferPushChannelAdminControl(address _newAdmin) external onlyPushChannelAdmin() {};

Description:
Changes the Push Channel admin's address to a new Address.

Arguments:

Argument	Type	Description
_newAdmin	address	Address of the new Admin

Core Functionalities

6. createChannelWithPUSH

function createChannelWithPUSH(
    ChannelType _channelType,
    bytes calldata _identity,
    uint256 _amount,
    uint256 _channelExpiryTime
) external whenNotPaused onlyInactiveChannels(msg.sender) onlyUserAllowedChannelType(_channelType) {};

Description:
Channel state changes from Inactive to Active. All imperative channel information (e.g., creation block number, total PUSH deposited, channel type) are stored.

Channel expiry time is stored if it's timebound; otherwise, it remains 0. The total Channel count increases by 1. The method emits an AddChannel() event with the Channel's address, Channel's Type, and Identity.

Arguments:

Argument	Type	Description
_channelType	Enum	Represents the type of Channel being created
_identity	bytes	Identity bytes of the Channel.
_amount	uint256	Total amount of PUSH being deposited
_channelExpiryTime	uint256	Time when the channel will expire and be ready for deletion

7. deactivateChannel

function deactivateChannel() external whenNotPaused onlyActivatedChannels(msg.sender) {};

Description:

Channel's state is changed from ACTIVE to DEACTIVATED. A minimum Pool Contribution of 1 PUSH token is deducted from the pool contribution of the channel. The remaining amount of PUSH after fee deduction is refunded back to the Channel Owner. The refunded amount is also subtracted from the Pool funds of the protocol.

Imperative on-chain details about the channel like channel state, new Channel pool contribution, new Channel weight, etc., are updated in the contract. Emits a DeactivateChannel() event with the Channel's address and Total Refund amount value.

8. reactivateChannel

function reactivateChannel(uint256 _amount) external whenNotPaused onlyDeactivatedChannels(msg.sender) {};

Description:
Channel's state is changed from DEACTIVATED to ACTIVE. The Fee amount is deducted from the received amount and added to Protocol Pool Fees. The remaining amount of PUSH after fee deduction is added to Protocol Pool fund.

Channel's new pool contribution and weight are updated. Imperative on-chain details about the channel like channel state, new Channel pool contribution, new Channel weight, etc., are updated in the contract. Emits a ReactivateChannel() event with the Channel's address and Total Deposited amount value.

Arguments:

Argument	Type	Description
_amount	uint256	PUSH amount to be deposited for the reactivation of the channel

9. blockChannel

function blockChannel(address _channelAddress) external whenNotPaused onlyPushChannelAdmin onlyUnblockedChannels(_channelAddress) {};

Description:
Channel's state is changed to BLOCKED state. Once blocked, the channel address cannot be reactivated. The pool contribution of the respective channel is deducted from Pool funds and added to pool fees.

Channel's pool contribution & weight are updated to new values, and no refund shall be given to the Channel owner when blocked. Emits a ChannelBlocked() event with the Channel's address.

Arguments:

Argument	Type	Description
_channelAddress	address	Address of the target channel to be blocked

10. verifyChannel

function verifyChannel(address _channel) public onlyActivatedChannels(_channel) {};

Description:
The target channel is marked as a verified channel. The Verifier's address of the target channel is stored in the channel's struct. This determines the type of verification tag the target channel has. For instance:

If the Channel was verified directly by Push Channel Admin, it will have a Primary Verification Tag.
If the Channel was verified by any other verified channel, it will have a Secondary Verification Tag.

Emits a ChannelVerified() event with the Channel's address and the Verifier's Address.

Arguments:

Argument	Type	Description
_channel	address	The address of the channel to be verified

11. unverifyChannel

function unverifyChannel(address _channel) public {};

Description:
Marks the target channel as Unverified. Emits a ChannelVerificationRevoked() event with the Channel's address and the address that revoked the verification tag of the channel.

Arguments:

Argument	Type	Description
_channel	address	The address of the channel whose verification shall be revoked

12. updateChannelMeta

function updateChannelMeta(
    address _channel,
    bytes calldata _newIdentity,
    uint256 _amount
) external whenNotPaused onlyChannelOwner(_channel) {};

Description:
Allows the Channel Owner to update their Channel Description or any imperative detail. The amount needed is the product of channel creation fees and the number of times this particular channel has been updated.

This approach makes it difficult to abuse the update channel feature. Adds the amount received to the Protocol Fees. Emits an UpdateChannel() event with the Channel's address and the New Identity bytes of the Channel.

Arguments:

Argument	Type	Description
_channel	address	Address of the channel
_newIdentity	bytes	New Identity bytes of the Channel.
_amount	uint256	Amount needed to upgrade the channel

Getter Functions

13. getChannelState

function getChannelState(address _channel) external view returns (uint256 state) {};

Description:
Returns the current state of the Channel. The returned value can be interpreted as:

0 -> INACTIVE
1 -> ACTIVATED
2 -> DeActivated By Channel Owner
3 -> BLOCKED by pushChannelAdmin/Governance

Arguments:

Argument	Type	Description
_channel	address	Address of the channel whose state is required

14. getChannelVerification

function getChannelVerification(address _channel) public view returns (uint8 verificationStatus) {};

Description:
Returns the verification tag of the channel's address passed in the argument. If the channel is not currently verified by anyone, the function returns 0. If verified by the Push Channel admin, it returns 1 (Primary verification tag). If verified by another verified channel, it returns 2 (Secondary verification tag).

Arguments:

Argument	Type	Description
_channel	address	Address of the channel whose verification tag is needed

15. destroyTimeBoundChannel

function destroyTimeBoundChannel(address _channelAddress) external whenNotPaused onlyActivatedChannels(_channelAddress) {};

Description:
If the channel's expiry date has been reached, the owner can proceed to delete it. The owner gets a refund of the channel’s amount in pool funds. However, the refund is only available for 14 days from the day the channel expires.

If the owner doesn’t delete the channel within this timeframe, the admin gains the power to delete the channel. When deleted by the admin, the refundable amount is not returned but is deducted from the pool fund and added to pool fees.

Arguments:

Argument	Type	Description
_channelAddress	address	Address of the channel to be destroyed

16. addSubGraph

function addSubGraph(bytes calldata _subGraphData) external onlyActivatedChannels(msg.sender) {};

Description:
This function allows users to pass subGraph data, in the form of bytes, which combines the Subgraph ID and Poll Interval. An event is emitted with the msg.sender and the bytes value.

Arguments:

Argument	Type	Description
_subGraphData	bytes	A combination of the Subgraph ID and Poll Interval

Deprecated State Variables

groupNormalizedWeight
groupHistoricalZ
groupLastUpdate
groupFairShareCount
channelHistoricalZ
channelFairShareCount

Push Core Contract

Types & Modifiers​

Storage Variables​

Storage variables for FSRatio Calculation​

Structs​

ChannelType​

channelState​

verifiedBy​

poolContribution​

channelLastUpdate​

channelStartBlock​

channelUpdateBlock​

channelWeight​

expiryTime​

Modifiers​

onlyPushChannelAdmin()​

onlyGovernance()​

onlyInactiveChannels()​

onlyActivatedChannels()​

onlyDeactivatedChannels()​

onlyUnblockedChannels()​

onlyChannelOwner()​

onlyUserAllowedChannelType()​

Mappings​

channels​

channelById​

channelNotifSettings​

nonces​

channelUpdateCounter​

usersRewardsClaimed​

Enums​

ChannelType​

ChannelAction​

Interface​

Methods​

1. setEpnsCommunicatorAddress​

2. setGovernanceAddress​

3. setFeeAmount​

4. setMinChannelCreationFees​

5. transferPushChannelAdminControl​

6. createChannelWithPUSH​

7. deactivateChannel​

8. reactivateChannel​

9. blockChannel​

10. verifyChannel​

11. unverifyChannel​

12. updateChannelMeta​

13. getChannelState​

14. getChannelVerification​

15. destroyTimeBoundChannel​

16. addSubGraph​

Deprecated State Variables​

Types & Modifiers

Storage Variables

Storage variables for FSRatio Calculation

Structs

ChannelType

channelState

verifiedBy

poolContribution

channelLastUpdate

channelStartBlock

channelUpdateBlock

channelWeight

expiryTime

Modifiers

onlyPushChannelAdmin()

onlyGovernance()

onlyInactiveChannels()

onlyActivatedChannels()

onlyDeactivatedChannels()

onlyUnblockedChannels()

onlyChannelOwner()

onlyUserAllowedChannelType()

Mappings

channels

channelById

channelNotifSettings

nonces

channelUpdateCounter

usersRewardsClaimed

Enums

ChannelType

ChannelAction

Interface

Methods

1. setEpnsCommunicatorAddress

2. setGovernanceAddress

3. setFeeAmount

4. setMinChannelCreationFees

5. transferPushChannelAdminControl

6. createChannelWithPUSH

7. deactivateChannel

8. reactivateChannel

9. blockChannel

10. verifyChannel

11. unverifyChannel

12. updateChannelMeta

13. getChannelState

14. getChannelVerification

15. destroyTimeBoundChannel

16. addSubGraph

Deprecated State Variables