How r-near/near-sdk-py works
Main Components
• Core NEAR Functionality:
• This is primarily under the “src/near” directory and includes files like context.py, storage.py, math.py, etc.
• It handles low-level blockchain interactions (e.g., blockchain context, economics, registers, and validators).
• NEAR SDK Python Interface:
• Found under “src/near_sdk_py” and its subdirectories. This is the heart of the SDK, offering the core “Contract” class, decorators (e.g., @call, @view, @init), and a rich set of utilities.
• Includes the Pythonic collections API (in the “collections” subdirectory) to provide a dictionary-like storage interface as well as multiple collection types (lookup maps, unordered maps/sets, tree maps, vectors).
• Promises and Cross-Contract Calls:
• Located in both “src/near” (promises.py) and “src/near_sdk_py/promises”. This is crucial for implementing cross-contract calls with method chaining, callbacks, and batch operations.
• Documentation and Examples:
• The “docs” directory (with separate sections for collections and promises) shows how the design is meant to be used.
• The README and the examples therein illustrate how developers will write contracts that interact with the SDK.
• Testing and Integration:
• “integration_tests” and “tests” directories include integration tests and performance benchmarks that validate the contract behaviors, simulate a blockchain environment, and ensure performance.
• CI/CD and DevOps:
• The “.github” directory with workflows (e.g., lint, release, tests) indicates automated quality checks and deployment processes.
Relationships and Interactions
• The core module (src/near) provides low-level blockchain functions that underpin the higher-level SDK.
• The NEAR SDK Python interface (src/near_sdk_py) wraps these lower-level functions into an easier-to-use, object-oriented API.
• The Contract base class exposes a Pythonic interface for contract authors (illustrated in the README), and it leverages both collections for storage and promises for cross-contract calls.
• The “docs” and “integration_tests” serve as validations and usage examples that interact directly with these modules.
• Build tools and CI/CD workflows ensure code quality and maintain the integrity of these interactions.
Architectural Patterns and Design Principles
• Modularization: The system is clearly split into modules with specific concerns (blockchain context, storage, collections, promises). Each module interacts via well-defined interfaces.
• Decorator Pattern: The use of Python decorators (e.g., @init, @call, @view) to designate behavior in contract methods is a key aspect.
• Layered Architecture: From low-level blockchain operations (e.g., context, economics) up through the SDK layer (contracts and API utilities) to the application-level (user contracts), there’s a clear separation.
• Testing and CI Integration: Integration tests and performance benchmarks emphasize the need for robust, repeatable testing.
Final Recommendations for the Principal Software Engineer
• Dependency flows and interactions (for example, show how data flows from a contract method call, through the SDK decorators, invoking lower-level blockchain context operations, and then returning results to the contract).
• Use annotations where needed to note design decisions (e.g., use of decorators for method dispatch, promise chaining for asynchronous cross-contract calls, and modular separation for maintainability).