Push Comm Contract

Unlike the Push core smart contract, the communicator protocol is designed to be deployed on multiple chains. This is also one of the imperative reasons behind the communicator contract being lightweight and less reliant on Push Core.

The Push Communicator protocol is comparatively quite simple. The communicator protocol includes features that allow users to subscribe to a channel, unsubscribe from a channel as well as the imperative one, i.e., sending notifications.

As the communicator protocol can be deployed on various chains, it allows us to trigger notifications on multiple chains and not just the Ethereum blockchain.

important

Push Communicator smart contracts are necessary to be deployed on any chain where notification directly from smart contracts feature is enabled.

Types & Modifiers

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

Storage Variables

  address public governance;
  address public pushChannelAdmin;
  uint256 public chainID;
  uint256 public usersCount;
  bool public isMigrationComplete;
  address public EPNSCoreAddress;
  string public chainName;
  string public constant name = "EPNS COMM V1";

Structs

struct User {
  bool userActivated;
  bool publicKeyRegistered;

  uint256 userStartBlock;

  uint256 subscribedCount;
  mapping(address => uint8) isSubscribed;
  mapping(address => uint256) subscribed;
  mapping(uint256 => address) mapAddressSubscribed;
}

The User struct in the Push Communicator smart contract stores all the crucial data of a particular user on the smart contract —

userActivated

• Depicts whether or not a user is ACTIVE

publicKeyRegistered

• Returns TRUE if the user's PUBLIC KEY has been registered in the communicator

userStartBlock

• Represents the block number when the user was added to the protocol

subscribedCount

• Keeps trakc of the total number of channels a user is subscribed to**

isSubscribed

• Keeps track of whether or not a user is subscribed to a specific channel address.

subscribed

• Maps channel address to ID

mapAddressSubscribed

• Maps ID to Channel Address

Modifiers

onlyPushChannelAdmin()

• Only allows Push Channel Admin to access the function

onlyEPNSCore()

• Only allows EPNS Core Contract to access a particular function
• Specifically used in the subscribeViaCore() fucntion

sendNotifViaSignReq()

• Ensures that all the necessary checkpoints before sending notification from EPNS Communicator is passed.
• Used in the sendNotifBySig() function.

Mappings

users

• mapping(address => User) public users;
• Maps a user's address to the User struct

nonces

• mapping(address => uint256) public nonces;
• Keeps track of the nonce of a specific address
• Specifically used in the Meta transaction functions

mapAddressUsers

• mapping(uint256 => address) public mapAddressUsers;
• Maps ID to User's address
• Updated in the _addUser() function of the protocol

userToChannelNotifs

• mapping(address => mapping(address => string)) public userToChannelNotifs;
• Keeps track the user's Notification settings for a specific channel

delegatedNotificationSenders

• mapping(address => mapping(address => bool)) public delegatedNotificationSenders;
• Keeps track of valid delegate notification sender for a particular channel

Methods

---

Only Admin Setter Functions

---

1. setEPNSCoreAddress

function setEPNSCoreAddress(address _coreAddress)
        external
        onlyPushChannelAdmin
    {};

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

Arguments:

Argument	Type	Description
_coreAddress	address	Address of the EPNS Communicator smart contract's address

---

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. 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

CheckPoints:

• Can only be called by the current Push Channel Admin.
• _newAdmin address being passed as an argument must be a valid address.
• _newAdmin address being passed as an argument must not be the already existing Push Channel Admin's address

---

Core Functionalities

---

4. sendNotification

function sendNotification(
        address _channel,
        address _recipient,
        bytes memory _identity
    ) external returns (bool) {};

Description:
If any one of the conditions is met, the function is executed, emitting a SendNotification event.

Arguments:

Argument	Type	Description
_channel	address	Address of the Channel from which the notification will be sent
_recipient	address	Address of the notification recipient
_identity	bytes	Identity bytes of the Channel

CheckPoints:
The sendNotification() is executed if any one of the following conditions is satisfied:

• If the _channel is a zero address, then the caller of the function must be the Push Channel Admin.
• If the _channel address passed in the argument is any active channel in the protocol, then the sendNotification() must be called by the channel owner.
• ... (and so on, for the remaining conditions)

---

5. addDelegate

function addDelegate(address _delegate) external {};

Description:
Allows a channel owner to approve a specific wallet address as the delegate notification sender for the channel. Once approved, the delegate can send notifications on behalf of the channel.

Arguments:

Argument	Type	Description
_delegate	address	Address of the delegate being added

---

6. removeDelegate

function removeDelegate(address _delegate) external {};

Description:
Allows a channel owner to revoke the approval of its delegate notification sender. Once revoked, the delegate cannot send notifications on behalf of that channel.

Arguments:

Argument	Type	Description
_delegate	address	Address of the delegate being removed

---

Subscribe & Unsubscribe Functions

---

7. subscribe

function subscribe(address _channel) external returns (bool) {};

Description:
Marks the caller as a valid subscriber of the channel. The subscribe count of the user is incremented.

Arguments:

Argument	Type	Description
_channel	address	Address of the channel the user is subscribing to

CheckPoints:

• The _channel argument passed in the function must be a valid channel in an ACTIVE state.
• The caller of the function (subscriber) must not already be subscribed to the channel.
• ... (additional checkpoints as needed)

---

8. batchSubscribe

function batchSubscribe(address[] calldata _channelList) external returns (bool) {};

Description:
Allows a user to subscribe to a list of different channels simultaneously.

Arguments:

Argument	Type	Description
_channelList	address[]	List of channel addresses the user wants to subscribe to

CheckPoints:

• The channel addresses passed in the function must be valid channels in an ACTIVE state.
• The caller of the function (subscriber) must not already be subscribed to the channels.
• ... (additional checkpoints as needed)

---

9. subscribeViaCore

function subscribeViaCore(address _channel, address _user) external onlyEPNSCore returns( bool) {};

Description:
Allows the EPNS Core smart contract to perform necessary subscribe actions whenever a user creates their own channel.

Arguments:

Argument	Type	Description
_channel	address	Address of the channel to which the user is subscribing
_user	address	Address of the user being subscribed

CheckPoints:

• It can only be called by the EPNSCore smart contract.

---

10. unsubscribe

function unsubscribe(address _channel) external returns (bool) {};

Description:
Unmarks the caller as a subscriber of the channel. The subscribe count of the user is decremented.

Arguments:

Argument	Type	Description
_channel	address	Address of the channel the user is unsubscribing from

CheckPoints:

• The caller of the unsubscribe() function should already be a subscriber of the _channel.

---

11. batchUnsubscribe

function batchUnsubscribe(address[] calldata _channelList) external returns (bool) {};

Description:
Allows a user to unsubscribe from a list of channels simultaneously.

Arguments:

Argument	Type	Description
_channelList	address[]	List of channel addresses the user wants to unsubscribe from

CheckPoints:

• The caller of the function should already be a subscriber of the list of channels provided as argument.

---

12. _addUser

function _addUser(address _user) private returns (bool userAlreadyAdded) {};

Description:
Checks whether the user address passed as an argument is activated in the protocol. If not already added, the function activates the user's address and performs certain operations.

Arguments:

Argument	Type	Description
_user	address	Address of the user being checked/added

---

13. broadcastUserPublicKey

function broadcastUserPublicKey(bytes calldata _publicKey) external {};

Description:
The function checks if the given _publicKey is already broadcasted in the protocol. If not, it marks the publicKeyRegistered member as true.

Arguments:

Argument	Type	Description
_publicKey	bytes	Public key data being broadcasted

---

14. verifyChannelAlias

function verifyChannelAlias(string memory _channelAddress) external {};

Description:
An essential function for channel owners to verify their channel alias. The entire verification procedure is handled by the PUSH Nodes.

Arguments:

Argument	Type	Description
_channelAddress	string	Address or alias of the channel to verify

---

15. unsubscribeViaCore

function unSubscribeViaCore(address _channel, address _user) external onlyEPNSCore returns (bool) {};

Description:
This function manages unsubscribing a user from a channel, with the call restricted to the EPNSCore smart contract.

Arguments:

Argument	Type	Description
_channel	address	Address of the channel to unsubscribe from
_user	address	Address of the user to unsubscribe

---

Meta Transaction Functions

The EPNS Communicator protocol supports meta transactions or, in other words, gasless transactions. These allow users to interact with functions without incurring gas fees.

Instead of incurring the gas costs themselves, they sign a transaction and then an operator submits it on their behalf. The protocol then verifies the signature and executes the required function.

---

16. subscribeBySig

function subscribeBySig(
        address channel,
        address subscriber,
        uint256 nonce,
        uint256 expiry,
        uint8 v,
        bytes32 r,
        bytes32 s
    ) external {};

Description:
This function enables a subscription through a signature verification process. It checks the signer's validity, nonce, and expiration before processing the subscription.

Arguments:

Argument	Type	Description
channel	address	Channel to which the user wants to subscribe
subscriber	address	Address of the user subscribing
nonce	uint256	Nonce value for the transaction
expiry	uint256	Expiration timestamp for the signature
v	uint8	ECDSA signature parameter
r	bytes32	ECDSA signature parameter
s	bytes32	ECDSA signature parameter

CheckPoints:

• Signer's address must not be invalid.
• Nonce passed as an argument should be a valid one.
• Transaction must not be expired.

---

17. unsubscribeBySig

function unsubscribeBySig(
        address channel,
        address subscriber,
        uint256 nonce,
        uint256 expiry,
        uint8 v,
        bytes32 r,
        bytes32 s
    ) external {};

Description:
Allows a user to unsubscribe from a channel using a signature. This function checks the signer's validity, nonce, and expiration.

Arguments:

Argument	Type	Description
channel	address	Channel from which the user wants to unsubscribe
subscriber	address	Address of the user unsubscribing
nonce	uint256	Nonce value for the transaction
expiry	uint256	Expiration timestamp for the signature
v	uint8	ECDSA signature parameter
r	bytes32	ECDSA signature parameter
s	bytes32	ECDSA signature parameter

CheckPoints:

• Signer's address must not be invalid.
• Nonce passed as an argument should be a valid one.
• Transaction must not be expired.

---

18. sendNotifBySig

function sendNotifBySig(
        address _channel,
        address _recipient,
        address _signer,
        bytes calldata _identity,
        uint256 nonce,
        uint256 expiry,
        uint8 v,
        bytes32 r,
        bytes32 s
    ) external returns (bool) {};

Description:
Allows sending of a notification through the Communicator protocol using a signed transaction.

Arguments:

Argument	Type	Description
_channel	address	Channel through which the notification is being sent
_recipient	address	Address of the notification recipient
_signer	address	Signer's address
_identity	bytes	Identity data
nonce	uint256	Nonce value for the transaction
expiry	uint256	Expiration timestamp for the signature
v	uint8	ECDSA signature parameter
r	bytes32	ECDSA signature parameter
s	bytes32	ECDSA signature parameter

CheckPoints:

• Signer's address must not be invalid.
• Nonce passed as an argument should be a valid one.
• Transaction must not be expired.

---