Stack Chain

Stack Chain is a blockchain for bringing points onchain, allowing brands to create and fully own their loyalty programs.

At the heart of the chain is the Points Protocol, a core protocol for managing point systems that can be extended by developers.

Network Information

Stack Mainnet

Name	Value
Network Name	Stack
Description	The public mainnet for Stack.
Chain ID	78225
Currency Symbol	ETH
RPC Endpoint	https://rpc.stack.so
Bridge	https://bridge.stack.so
Block Explorer	https://explorer.stack.so
Points Protocol	0x000000000c2B4A5816cbb76e9bb3f70D175940A3
Points Interface	IPoints.sol
Observer Interface	IPointsObserver.sol

The Points Protocol

The Points Protocol is a Solidity smart contract that enables the creation and management of point systems. It provides a flexible and modular approach to implementing point-based systems.

Features

• Create multiple point systems, each with its own unique ID
• Add and subtract points from user balances within a point system
• Retrieve point balances and total points within a point system
• Perform batch operations to add or subtract points for multiple users simultaneously
• Support for managing administrators and external contracts (issuers) within a point system
• Set and retrieve metadata (URI) for each point system
• Observer pattern to notify external contracts of point balance changes

Usage

To interact with the Points Protocol, you can use the IPoints interface. The contract is deployed at the address 0x000000000c2B4A5816cbb76e9bb3f70D175940A3.

Creating a Point System

To create a new point system, call the createPointSystem() function. It will return the ID of the newly created point system.

Managing Points

• addPoints(uint256 systemId, address user, uint256 points): Add points to a user's balance within a specific point system.
• subtractPoints(uint256 systemId, address user, uint256 points): Subtract points from a user's balance within a specific point system.
• getPoints(uint256 systemId, address user): Retrieve the point balance of a user within a specific point system.
• getTotalPoints(uint256 systemId): Retrieve the total points within a specific point system.

Batch Operations

• addPointsBatch(uint256 systemId, address[] calldata users, uint256[] calldata points): Add points to multiple users' balances within a specific point system in a single transaction.
• subtractPointsBatch(uint256 systemId, address[] calldata users, uint256[] calldata points): Subtract points from multiple users' balances within a specific point system in a single transaction.
• addPointsBatchMultipleSystems(uint256[] calldata systemIds, address[] calldata users, uint256[] calldata points): Add points to multiple users' balances across different point systems in a single transaction.
• subtractPointsBatchMultipleSystems(uint256[] calldata systemIds, address[] calldata users, uint256[] calldata points): Subtract points from multiple users' balances across different point systems in a single transaction.

Managing Administrators and Issuers

• addAdmin(uint256 systemId, address admin): Add an administrator to a specific point system.
• removeAdmin(uint256 systemId, address admin): Remove an administrator from a specific point system.
• addIssuer(uint256 systemId, address contractAddress): Add an external contract (issuer) to a specific point system.
• removeIssuer(uint256 systemId, address contractAddress): Remove an external contract (issuer) from a specific point system.

Observer Pattern

• setObserver(uint256 systemId, address observer): Set an observer contract for a specific point system. The observer will be notified when points are added or subtracted from a user's balance.
• getObserver(uint256 systemId): Retrieve the observer contract for a specific point system.

Managing Metadata

• setURI(uint256 systemId, string calldata uri): Set the URI (metadata) for a specific point system.
• getURI(uint256 systemId): Retrieve the URI (metadata) for a specific point system.

Error Handling

The Points Protocol defines several custom errors to handle specific scenarios:

• OnlyAdmin(uint256 systemId, address user): Thrown when a non-admin user tries to perform an admin-only action.
• OnlyIssuer(uint256 systemId, address user): Thrown when a non-issuer contract tries to perform an issuer-only action.
• InsufficientPoints(uint256 systemId, address user, uint256 available, uint256 required): Thrown when a user doesn't have enough points for a specific operation.
• ArrayLengthMismatch(): Thrown when the lengths of input arrays for batch operations don't match.

Make sure to handle these errors appropriately in your code.

License

The Points Protocol is released under the MIT License.