# huuduynvc/buy-nft-func-smc architecture

> Architecture diagram of the GitHub repository huuduynvc/buy-nft-func-smc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/huuduynvc/buy-nft-func-smc
- Repository: https://github.com/huuduynvc/buy-nft-func-smc

## Overview

##### Project Type & Purpose
- This is a blockchain-based smart contract project designed to handle NFT interactions and sync listings between an in-game experience and an external marketplace (Getgems).
- It encapsulates the business logic within smart contracts (located in the “contracts” directory), uses wrapper classes to interface with these contracts (in “wrappers”), includes deployment and management scripts (in “scripts”), and has automated tests (in “tests”).

##### Analyzing the File Structure
- The “contracts” directory holds the core smart contract source code including multiple versions (buy-land.fc, buy-land-v2.fc, buy-land-v3.fc) and related dependencies such as standard libraries and utilities.
- The “wrappers” directory contains TypeScript files that serve as wrappers for the smart contracts, handling tasks like serialization/deserialization and compilation.
- The “scripts” directory is for various deployment scripts that would deploy the contracts to the blockchain.
- The “tests” directory contains specifications ensuring that smart contract functionalities (e.g., BuyLandV3 in tests/BuyLandV3.spec.ts) are verified.
- Configuration and tooling files (like package.json, jest.config.ts, tsconfig.json, etc.) outline the project’s development environment.

a. Main Components:
- Smart Contracts: Represented by the “contracts” directory. They include multiple versions of the BuyLand contracts and their auxiliary code (imports, NFT utilities, opcode implementations, and parameter definitions).
- Contract Wrappers: Found in the “wrappers” folder, these are the TypeScript interfaces to interact with the deployed smart contracts.
- Deployment Scripts: Under “scripts”, these handle deployment and controller functions for different contract versions.
- Testing Suite: In “tests”, these verify behavior and performance of contract code.
- External Components: External market integration with Getgems and the in-game logic/marketplace environment.
- Build/Tool Configurations: Build commands (like the blueprint commands) and testing commands form the overall development and CI/CD process.

b. Relationships/Interactions:
- The smart contracts are the core components that implement the business logic for buying NFTs. They interact with both in-game systems and external platforms.
- Contract wrappers serve as the intermediary between application logic and the underlying contract bytecode, encapsulating serialization and compilation details.
- Deployment scripts orchestrate pushing contracts onto the blockchain and may manage environment configurations.
- Tests validate that the contracts and wrappers behave as expected.
- Data flow: The user or another system initiates an NFT purchase which triggers a smart contract, leading to potential lifecycle events (listing cancellation on Getgems, ownership transfer in-game).

##### Architectural Patterns / Design Principles
- Separation of Concerns: Splitting core contract logic (contracts) from operational management (scripts) and interfacing (wrappers).
- Modular Versioning: Multiple contract versions (v1, v2, v3) suggest evolution and backward compatibility.
- Immutable Contract Logic: Using contracts as self-contained, testable modules.
- Automated Testing & Deployment: Ensuring reliability and ease of change via clearly separated tests and scripts.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% On-Chain Components
    subgraph "On-Chain Components"
        SC["Smart Contracts (contracts)"]:::contracts
        subgraph "Contract Versions"
            BuyL["Buy Land v1"]:::contracts
            BuyL2["Buy Land v2"]:::contracts
            BuyL3["Buy Land v3"]:::contracts
        end
        NFTUtils["NFT Utils"]:::contracts
        OpCodes["Op Codes"]:::contracts
        Params["Params"]:::contracts
        Stdlib["Stdlib"]:::contracts
    end

    %% Off-Chain Components
    subgraph "Off-Chain Components"
        subgraph "Contract Wrappers (wrappers)"
            BuyLandWrapper["BuyLand.ts"]:::wrappers
            BuyLandV2Wrapper["BuyLandV2.ts"]:::wrappers
            BuyLandV3Wrapper["BuyLandV3.ts"]:::wrappers
        end
        subgraph "Deployment Scripts (scripts)"
            DepBuyLand["deployBuyLand.ts"]:::scripts
            DepBuyLandHelper["deployBuyLandHelper.ts"]:::scripts
            DepBuyLandV2["deployBuyLandV2.ts"]:::scripts
            DepBuyLandV2Controller["deployBuyLandV2Controller.ts"]:::scripts
            DepBuyLandV3["deployBuyLandV3.ts"]:::scripts
            DepBuyLandV3Controller["deployBuyLandV3Controller.ts"]:::scripts
        end
        subgraph "Testing Suite (tests)"
            TestBuyLandV3["BuyLandV3.spec.ts"]:::tests
        end
    end

    %% External Services
    subgraph "External Services"
        InGame["In-Game Marketplace"]:::external
        Getgems["Getgems Marketplace"]:::external
    end

    %% Connections
    InGame -->|"trigger_purchase"| SC
    SC -->|"cancel_listing"| Getgems

    %% Wrappers invoking smart contracts (version-specific)
    BuyLandWrapper -->|"invokes"| BuyL
    BuyLandV2Wrapper -->|"invokes"| BuyL2
    BuyLandV3Wrapper -->|"invokes"| BuyL3

    %% Deployment Scripts deploying contracts
    DepBuyLand -->|"deploy_contract"| BuyL
    DepBuyLandV2 -->|"deploy_contract"| BuyL2
    DepBuyLandV3 -->|"deploy_contract"| BuyL3

    %% Testing Suite validating contracts
    TestBuyLandV3 -->|"validate_contract"| BuyL3

    %% Additional interactions: Scripts may use helper controllers
    DepBuyLandV2Controller -->|"orchestrates"| DepBuyLandV2
    DepBuyLandV3Controller -->|"orchestrates"| DepBuyLandV3

    %% Color Definitions
    classDef contracts fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef wrappers fill:#ABEBC6,stroke:#1E8449,stroke-width:2px;
    classDef scripts fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef tests fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef external fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;

    %% Click Events for Smart Contracts
    click BuyL "https://github.com/huuduynvc/buy-nft-func-smc/blob/main/contracts/buy-land.fc"
    click BuyL2 "https://github.com/huuduynvc/buy-nft-func-smc/blob/main/contracts/buy-land-v2.fc"
    click BuyL3 "https://github.com/huuduynvc/buy-nft-func-smc/blob/main/contracts/buy-land-v3.fc"
    click NFTUtils "https://github.com/huuduynvc/buy-nft-func-smc/blob/main/contracts/nft-utils.fc"
    click OpCodes "https://github.com/huuduynvc/buy-nft-func-smc/blob/main/contracts/op-codes.fc"
    click Params "https://github.com/huuduynvc/buy-nft-func-smc/blob/main/contracts/params.fc"
    click Stdlib "https://github.com/huuduynvc/buy-nft-func-smc/blob/main/contracts/imports/stdlib.fc"

    %% Click Events for Contract Wrappers
    click BuyLandWrapper "https://github.com/huuduynvc/buy-nft-func-smc/blob/main/wrappers/BuyLand.ts"
    click BuyLandV2Wrapper "https://github.com/huuduynvc/buy-nft-func-smc/blob/main/wrappers/BuyLandV2.ts"
    click BuyLandV3Wrapper "https://github.com/huuduynvc/buy-nft-func-smc/blob/main/wrappers/BuyLandV3.ts"

    %% Click Events for Deployment Scripts
    click DepBuyLand "https://github.com/huuduynvc/buy-nft-func-smc/blob/main/scripts/deployBuyLand.ts"
    click DepBuyLandHelper "https://github.com/huuduynvc/buy-nft-func-smc/blob/main/scripts/deployBuyLandHelper.ts"
    click DepBuyLandV2 "https://github.com/huuduynvc/buy-nft-func-smc/blob/main/scripts/deployBuyLandV2.ts"
    click DepBuyLandV2Controller "https://github.com/huuduynvc/buy-nft-func-smc/blob/main/scripts/deployBuyLandV2Controller.ts"
    click DepBuyLandV3 "https://github.com/huuduynvc/buy-nft-func-smc/blob/main/scripts/deployBuyLandV3.ts"
    click DepBuyLandV3Controller "https://github.com/huuduynvc/buy-nft-func-smc/blob/main/scripts/deployBuyLandV3Controller.ts"

    %% Click Event for Testing Suite
    click TestBuyLandV3 "https://github.com/huuduynvc/buy-nft-func-smc/blob/main/tests/BuyLandV3.spec.ts"
```
