How wh00hw/zizza-backend works
Project Type & Purpose
• This is a backend server that exposes REST APIs to perform various cryptocurrency operations (e.g., setting up an agent, depositing funds, swapping assets, and withdrawals) on the NEAR and Zcash blockchains.
• It is designed as an API service and can be run as a standalone container via Docker or integrated as a Python package. The project also uses a submodule (zecwallet-light-cli) for interfacing with Zcash.
Main Components
• Client/Frontend:
• API Server:
– Represent the main server component that receives and processes API requests. This is implemented in server.py (likely using uvicorn for running the ASGI app) and exposes endpoints like /execute and /status/{task_id}.
• ZizZA Package Modules:
– API Module: The entry point for all operations (in zizza/api.py). This encapsulates methods like set_agent, get_wallet_summary, deposit, swap, withdraw, etc.
– Agent Module: Handles agent setup and initialization (found in zizza/agent.py).
– Middleware Module: Likely responsible for request processing and additional cross-cutting concerns (in zizza/middleware.py).
• Blockchain-specific Integrations:
– NEAR Components: Located within zizza/near, these modules (account.py, asset.py, intent_contract.py, nep413_signer.py, omni_bridge.py, solver.py, etc.) encapsulate functionalities specific to interfacing with the NEAR blockchain.
– Zcash Components: Located within zizza/zcash. Modules such as wallet.py interface with Zcash, and an external submodule (zecwallet-light-cli) provides deeper integration for Zcash wallet operations.
• Asynchronous Task Management:
– The server processes multiple operations asynchronously. Each batch of operations is associated with a unique task_id to track progress. Represent a “Task Queue” or “Task Manager” component handling this process flow.
Relationships and Interactions
• Request Flow:
– Show external clients making REST calls to the API Server.
– The API Server passes requests into the business logic encapsulated within the API module inside the ZizZA package.
• Internal Interactions:
– The API module delegates specific blockchain operations to either the NEAR or Zcash submodules.
– The NEAR and Zcash modules interact with blockchain-specific libraries and endpoints to execute operations like wallet initialization, checking balances, or performing asset swaps.
– The asynchronous task system tracks execution, and status queries (GET /status/{task_id}) are routed back to the API module for response construction.
• Submodule Integration:
– Represent the integration of the zecwallet-light-cli submodule under the Zcash component, showing that it is built separately (via Cargo) but integrated into the overall Zcash workflow.
Architectural Patterns & Technologies
• Modular Design: The separation into distinct directories (near, zcash, etc.) shows a clear modular approach.
• RESTful API Design: The server exposes multiple endpoints for CRUD-like operations and blockchain interactions.
• Asynchronous Processing: The use of asynchronous execution (via task IDs and parallel operations) is a fundamental design element.
• Containerization and Deployment: Usage of Dockerfile, .dockerignore indicates that containerization is a key part of deployment.
• Environment & Dependency Management: Virtual environments are provided via requirements.txt.
• Technology Stack:
• Python (core backend logic)
• Uvicorn (for running the ASGI application)
• Docker (for containerized deployments)
• Rust (for the Zcash wallet submodule via Cargo)
• Use Clear Labels: Each component (e.g., “API Server”, “NEAR Gateway”, “Zcash Wallet Integration”, “Task Manager”) should be clearly labeled.
• Layer the components logically: External Client at the top, followed by the API Server layer, then internal modules and integrations, and finally external blockchain networks.