How kncos/tandapay-smart-contract-api works
Project Type and Purpose
• Type: A smart contract API library.
• Purpose: To abstract and encapsulate the low-level details of interacting with the TandaPay smart contract, provide specialized read and write methods, enforce role-based access, and allow building additional business logic on top.
• Key Feature: TandaPay Manager that conditionally exposes different methods based on the client’s capabilities (read-only vs. wallet client) and roles.
Key Components
a. TandaPay Manager:
• This is the central component encapsulated in src/tandapay_manager. It acts as the main gateway, combining both read and write functionalities.
• It has sub-components for read methods (in src/tandapay_manager/read) and write methods (in src/tandapay_manager/write), with further role-based splitting (e.g., member, public, secretary method groups).
b. Smart Contract Wrappers (Contracts):
• Found under src/_contracts, these files (e.g., FaucetToken.ts, Multicall3.ts, TandaPay.ts) define the low-level contract interactions and artifacts (ABI/bytecode).
• They are the hardcoded connection layer to the TandaPay smart contract.
c. Interfaces:
• This separation improves code clarity and maintainability.
d. Actions and Higher-Level Logic:
• Under src/tandapay_actions, you have modules that provide “action” wrappers (batch reading, public writes, normal read actions) for interacting with the contract.
• These act as more user-friendly or business logic specific procedures built on top of the contract wrappers.
e. Macros/Utilities:
• The src/tandapay_macros directory holds additional procedures like auto reorganization routines, custom filtering logic, and initialization state helpers.
• They provide automation and extended capabilities that support and optimize core operations.
f. Utilities and Custom Types:
• Generic helper functions and type definitions (found in files like src/tandapay_utils.ts and src/types.ts) that support all of the above components.
g. Testing Suite:
• The test directory shows comprehensive unit and integration tests.
Relationships and Interactions
• The TandaPay Manager is the central orchestrator. It interacts with:
• The underlying Smart Contract Wrappers (to execute low-level reads/writes).
• Specific interfaces to map raw smart contract data to clear, custom types.
• High-level action modules which wrap common interactions.
• Macros that provide automated procedures (e.g., auto reorg, state initialization).
• A directional flow starts from the client using the TandaPay Manager, which then routes calls appropriately to read or write submodules.
Architectural Patterns and Design Principles
• Separation of Concerns: Clear modular division (interfaces, actions, manager, macros) ensures that each component has a distinct responsibility.
• Abstraction Layer: The library acts as an intermediary to shield higher-level business logic from changes in the underlying smart contract.
• Role-based Access: Write methods are separated based on the role of the calling account, which is crucial for the application’s permission management.
• Testability: A strong emphasis on integration and unit tests is evident, which validates both internal business logic and smart contract behavior.