How forta-network/forta-bot-sdk works
Main components
• CLI Application: This component encapsulates all the commands (init, run, push, publish, enable/disable, keyfile, logs) that allow users to perform tasks from command line.
• SDK Libraries:
– Typescript/JavaScript SDK (in the “sdk” folder and “cli” modules that use it): Contains functionalities for interacting with blockchain events, alerts, and for managing bot configurations.
– Python SDK (in the “python-sdk” folder): Offers equivalent functionality for Python-based detection bots.
• Starter Projects: Sample projects organized by language (js, py, ts under the “starter-project” folder) that show how to use the SDK and CLI.
• Smart Contract Wrappers: Located under “cli/contracts”, these provide ABI files and helper functions to interact with deployed smart contracts (agent registry, staking contracts, etc.).
• Utility Modules and Test Suites: Utility functions (under “cli/utils” and related directories) perform common tasks (e.g., interacting with IPFS, fetching logs or blockchain data, decoding JWTs) and automate testing (test files across the project).
• CI/CD Pipeline: GitHub workflows under “.github/workflows” provide automated testing and continuous integration for both the CLI and SDK.
Relationships and data flows
• User Input (commands issued via the CLI) flows into the CLI Application component.
• The CLI commands then invoke underlying utility functions and methods from the SDK libraries.
• SDK functions communicate with external systems such as:
– Blockchain networks (using JSON-RPC via ethers.js/web3, or direct JSON-RPC calls),
– IPFS nodes (for uploading files or retrieving agent information),
– gRPC services (as indicated by the proto definitions and controllers in the CLI “run/server” folder).
• The smart contract wrappers are used by both the CLI and SDK to interact with blockchain contracts (for agent registration, staking, etc.).
• The Python SDK is parallel to the JS/TS SDK, exposing many equivalent functionalities, and also includes its own test and build pipelines.
Important architectural patterns/design principles
• Separation of Concerns: There is a clear separation between the CLI (user interface), the SDK libraries (business logic) and the starter projects (usage examples).
• Modularity: The project is structured into multiple well-defined modules (commands, contracts, utilities, SDK core) to enable easy extension and maintenance.
• Cross-Language Support: Two distinct SDKs (JavaScript/TypeScript and Python) indicate design considerations for supporting developers in different ecosystems.
• Test-Driven Development: The ample presence of unit tests and CI/CD pipelines shows that automated testing is integral to the design.
Detail relevant technologies and frameworks
• Node.js/TypeScript for the CLI and main SDK, along with test frameworks like Jest.
• Python (with pytest) for the Python-sdk.
• Ethers.js and/or web3 (for blockchain interactions).
• gRPC (as referenced in the “run/server” subdirectory that contains proto definitions).
• IPFS (for some storage and retrieval functionalities as shown by the “ipfs” utilities).
• GitHub Actions for CI/CD (using YAML workflows).
Detail without overcomplicating
• Annotations, if needed, to note design principles (modularity, separation of concerns) or protocol interactions (JSON-RPC, gRPC).