Hierarchical Module (hierachain/hierarchical/*)

1. Tổng quan

Module hierarchical triển khai kiến trúc sổ cái hai tầng của HieraChain. Các chuỗi con (Sub-Chain) xử lý các sự kiện nghiệp vụ miền và lưu trữ trạng thái chi tiết tại cục bộ. Chuỗi chính (Main Chain) lưu trữ các bằng chứng mật mã và mã băm gốc do Sub-Chain gửi lên. Sự phân tách này duy trì tính riêng tư của dữ liệu nghiệp vụ, giảm tải xác thực cho Main Chain và mở rộng quy mô theo chiều ngang bằng cách phân chia tải giữa các chuỗi.

2. Các thành phần nền tảng

Các thành phần được tổ chức trong các gói chuyên biệt dưới hierachain/hierarchical/.

2.1 Chuỗi chính Main Chain (main_chain/base.py)

• Lưu trữ các bằng chứng khối mật mã thay vì dữ liệu sự kiện thô.
• Lọc đệ quy metadata đăng ký Sub-Chain trước khi lưu vào registry, authority đồng thuận hoặc event đăng ký; bản tóm tắt chỉ trả bản đã lọc.
• Cung cấp hook xác thực ZK; tạo và xác minh proof production chưa được triển khai.
• Kiểm tra tính hợp lệ của các điểm neo liên chuỗi theo cơ chế đồng thuận thẩm quyền hoặc liên minh.

2.2 Chuỗi con Sub-Chain (sub_chain/base.py)

• Vận hành quy trình nghiệp vụ chuyên biệt cho từng miền hoặc phòng ban.
• Đóng gói sự kiện nghiệp vụ vào các khối và tính toán Merkle root.
• Tạo bằng chứng trạng thái định kỳ để gửi lên Main Chain.

Khởi động đọc header block và event theo thứ tự bằng một truy vấn SQL theo khoảng, vẫn kiểm tra Merkle, hash, chữ ký từ khóa tin cậy, khoảng trống index và liên kết chuỗi. Sub-Chain nhận snapshot bootstrap đã xác thực của ordering một lần thay vì đọc lại toàn chuỗi; các lần đồng bộ sau đọc storage mới. Recovery dựng lại index thực thể, index loại event và counters qua helper index chung của Blockchain, để truy vấn phản ánh sổ cái đã khôi phục.

validate_cross_chain_consistency() so sánh hash tip của từng Sub-Chain với proof MainChain mới nhất đã lưu bền vững. Thiếu proof hoặc proof không khớp luôn làm overall_consistent thành false. Nếu tip đã tiến lên nhưng khoảng gửi proof cấu hình chưa hết, kết quả của chain đó là consistent: false, pending: true; pending giải thích thời gian chờ theo lịch nhưng không xác nhận tip chưa được neo. Proof MainChain chỉ được tính là điểm neo sau khi signed block vượt qua bước đọc lại từ storage bền vững.

2.3 Quản lý phân cấp Hierarchy Manager (hierarchy_manager/base.py)

• Điều phối vòng đời chuỗi, xác thực liên chuỗi và cấu hình đa tổ chức.
• Quản lý các kênh trao đổi (channel), bộ sưu tập dữ liệu riêng tư và giao dịch Two-Phase Commit (2PC).
• Tổng hợp báo cáo tính toàn vẹn hệ thống trên toàn bộ các chuỗi đã đăng ký.

HierarchyManager vẫn là coordinator công khai, sở hữu tài nguyên, trạng thái chung và lock. Module nội bộ recovery.py replay và xác thực lịch sử chuỗi bền vững; registry.py xử lý snapshot quyền truy cập, migration, ghi có điều kiện, refresh và rollback. organization.py tạo view thành viên/channel, còn validation.py tạo báo cáo tính toàn vẹn. Các helper dùng chung trạng thái của coordinator, không tạo registry hay storage owner thứ hai. Signature method, thứ tự recovery, hook cleanup và hợp đồng storage hiện có được giữ lại.

Ranh giới hỗ trợ tính năng

get_cross_chain_statistics()["cross_chain_operations"] là trường dự phòng hiện trả 0, không phải số operation hoàn tất đã đo. Có method facade hay tùy chọn cấu hình chưa đủ để xác nhận tính năng hoạt động xuyên suốt.

Metadata truy cập tổ chức/thành viên/channel được lưu cùng _revision nội bộ và _channel_ledger_version: 1. Registry snapshot không chứa lịch sử ledger của channel. SQLite và PostgreSQL dùng ghi có điều kiện nguyên tử. RedisLedgerAdapter hỗ trợ block hierarchy đã ký và dùng lại helper record channel Redis sau khi kiểm tra cấu hình AOF bền dữ liệu; xem điều kiện Redis ledger. Provisioning qua manager tải lại và thử tối đa ba lần khi ghi không thành công. Provisioning thành viên qua REST kiểm tra lại quyền administrator đã xác thực trong mỗi lần retry. Conflict cấu hình channel trả thất bại và rollback thay đổi cục bộ, yêu cầu endorsement mới trước khi thử lại. Thao tác đọc và kiểm tra truy cập channel làm mới metadata chung và chỉ đọc record chưa xử lý của channel được yêu cầu, giữ nguyên object channel; backend không truy cập được hoặc trạng thái đã lưu bị mất sẽ từ chối truy cập. Manager chỉ dùng bộ nhớ giữ trạng thái cục bộ.

Registry snapshot cũ chứa ledger được kiểm tra và chuyển đổi trong quá trình recovery. Việc thay registry và tạo record khởi đầu cho từng channel được commit nguyên tử; migration thất bại giữ nguyên snapshot cũ. Cần nâng cấp đồng thời mọi registry writer và dừng writer cũ trước migration: không hỗ trợ chạy lẫn writer dùng snapshot với writer ghi nối tiếp. Storage adapter tùy chỉnh phải hỗ trợ save_hierarchy_registry(state, expected_revision=..., channel_ledgers=...), khởi tạo nguyên tử các ledger seed được cung cấp và từ chối revision cũ. Adapter cũng phải triển khai append_channel_record(channel_id, record, expected_sequence=..., expected_registry_revision=...) và load_channel_records(channel_id, after_sequence=...).

Submission channel ghi nối tiếp một event record bền vững trước khi trả thành công; lỗi storage trả HTTP 503 và không thay đổi pending events hay bộ đếm. Mỗi lần append kiểm tra nguyên tử cả revision quyền truy cập trong registry và sequence của channel, nên worker có trạng thái cũ không thể ghi đè lịch sử hoặc append bằng snapshot quyền đã bị thu hồi. Finalization ghi nối tiếp một signed block record tiêu thụ batch event đang chờ. SQL adapter lưu head và record của channel trong channel_ledger_heads và channel_ledger_records; các helper Redis dùng list riêng từng channel với kiểm tra WATCH/MULTI. Ghi event giữ nguyên metadata registry và không serialize block cũ hay các channel khác. Finalization chỉ ghi batch block mới.

Restart replay record của channel, khôi phục pending events, kiểm tra từng finalized block bằng trusted keys và batch pending tương ứng, rồi dựng lại bộ đếm submission. Các lần refresh sau chỉ áp dụng suffix mới và cập nhật bộ đếm tăng dần. Suffix không hợp lệ giữ nguyên trạng thái ledger cục bộ. Query vẫn chỉ trả finalized blocks; ACK nhận event chưa đồng nghĩa đã finalize. Channel tạo trực tiếp và manager chỉ dùng memory vẫn là dữ liệu tạm. Việc xác thực toàn bộ khi startup, bộ nhớ ledger và dữ liệu record giữ lại vẫn tăng theo lịch sử; thay đổi này chưa có retention/compaction. Thao tác truy cập cục bộ vẫn giữ registry lock của manager.

2.4 Đa tổ chức, kênh và dữ liệu riêng tư

• multi_org.py: Quản lý các tổ chức thành viên, chứng chỉ và định danh MSP.
• channel/manager.py: Phân vùng giao tiếp giữa các nhóm tổ chức cụ thể.
• private_data.py: Cung cấp collection mã hóa trong bộ nhớ và helper hash; lưu bền vững và tự động neo vào ledger cần tích hợp từ ứng dụng gọi.

2.5 Quyền truy cập Organization–SubChain

Tổ chức và SubChain có quan hệ nhiều–nhiều. Quyền áp dụng cho thành viên đã đăng ký, có identity lưu trữ khớp user ID, tổ chức và role. User ID lấy từ xác thực API; request body không thể chọn identity khác. API key vẫn phải có quyền tài nguyên tương ứng bên cạnh quyền của tổ chức.

Endpoint đọc yêu cầu chains. GraphQL và WebSocket giữ kiểm tra tài nguyên của transport hiện có; stream WebSocket yêu cầu cả chains và events. Các quyền độc lập: write không bao hàm read, và role trong tổ chức không tự thêm quyền. Dùng scope API key giới hạn để kiểm soát từng người dùng.

Quản lý assignment yêu cầu key đã xác thực với cả chains và chains:manage. Administrator tổ chức không tự có quyền quản lý chain. Scope tài nguyên all hiện bao hàm quyền quản lý, vì vậy chỉ cấp cho administrator nền tảng.

SubChain và tổ chức phải tồn tại trước. PUT yêu cầu danh sách quyền không rỗng, chỉ gồm read, write, proofs; body không hợp lệ trả HTTP 422. Tài nguyên/assignment không tồn tại trả HTTP 404; thiếu quyền quản lý trả HTTP 403. Tạo tổ chức và đăng ký thành viên qua business API hiện có trước khi gán quyền.

manager.assign_organization_to_chain("logistics", "supply_chain", permissions=["read", "write"])
manager.can_access_chain("supply_chain", "alice", "read")
manager.get_chain_access("supply_chain")
manager.revoke_organization_from_chain("logistics", "supply_chain")

Method gán quyền Python mặc định dùng read và write nếu bỏ qua permissions, trả False khi thiếu tổ chức/SubChain và ném ValueError khi quyền không hợp lệ. Lệnh thay thế danh sách quyền hiện có của tổ chức đó. get_chain_access() trả None khi chain chưa được quản lý quyền và bản sao mapping khi đã được quản lý.

Tương thích và triển khai: chain chưa có assignment giữ hành vi API cũ theo scope tài nguyên hiện có. Assignment đầu tiên bật kiểm tra tổ chức cho mọi lượt đọc API đối với dữ liệu quá khứ và tương lai của SubChain đó. Thu hồi assignment cuối giữ mapping rỗng ở trạng thái được quản lý, từ chối thành viên cho đến khi cấp quyền mới. Không có API chuyển về trạng thái chưa quản lý. Nâng cấp toàn bộ API worker và registry writer trước khi bật assignment; không hỗ trợ chạy lẫn phiên bản. Tắt xác thực không cho phép truy cập chain đã quản lý quyền.

Quyền nằm trong trường chain_access của hierarchy registry hiện có, dùng retry revision và rollback; snapshot cũ thiếu trường này được tải như trạng thái chưa quản lý. Manager dùng chung SQLite/PostgreSQL/Redis làm mới registry khi kiểm tra quyền và từ chối nếu không đọc được trạng thái đã lưu. Manager chỉ dùng memory vẫn là dữ liệu tạm. WebSocket kiểm tra khi subscribe và trước mỗi broadcast của chain, kể cả subscription wildcard và theo loại event; thu hồi quyền chặn lượt gửi được kiểm tra sau đó nhưng không thu hồi dữ liệu đã gửi hoặc đã vào hàng đợi. Request đã vượt qua bước kiểm tra quyền có thể hoàn tất; ghi event SubChain không so sánh revision registry nguyên tử tại thời điểm append.

Đây là phân quyền API, không tạo ledger mã hóa riêng cho từng tổ chức. Proof MainChain, metadata đăng ký và bộ đếm tổng hợp của node vẫn dùng chung. Lời gọi trực tiếp đến object chain trong tiến trình là thao tác tin cậy; ứng dụng nhúng phải gọi can_access_chain() trước khi mở cho người dùng. Policy và ledger của channel vẫn độc lập, không tự gán SubChain hay neo proof.

Kiểm chứng Docker

.venv/bin/python docker/scripts/verify_chain_access.py --context orbstack

Bỏ --context orbstack để dùng Docker context hiện tại. Runner dựng wheel production và cả hai stage image Docker từ bản sao tạm của checkout hiện tại, gồm cả thay đổi cục bộ. Nó tạo identity và API key tạm, khởi động ba container API production có xác thực với SQLite/PostgreSQL/Redis, rồi gọi HTTP/WebSocket thật từ container kiểm thử riêng. Kiểm thử live không thay thế dependency của API.

Các bước kiểm tra gồm scope quản lý, quyền tổ chức đã chọn, ghi/đọc REST và GraphQL, secure event có chữ ký, gửi proof, trace entity, cho phép kết nối/thu hồi subscription WebSocket và hai lần tạo lại container ứng dụng với volume được giữ lại. Runner còn chạy bộ Docker runtime và lần lượt 20 file hồi quy trong Linux container, gồm kiểm thử backend registry dùng chung và coi skip là thất bại. Bộ hồi quy kiểm tra lọc broadcast; bộ live không thêm publisher tự động từ ledger sang WebSocket. Phạm vi này xác minh organization–chain, không kiểm thử consensus P2P hay stress/soak.

Log và JUnit XML được giữ trong thư mục báo cáo tạm mà runner in ra. Runner xóa container, network, volume và thông tin xác thực do nó tạo ngay cả khi thất bại. Deployment hiện có và thư mục dữ liệu của repository không được mount vào stack kiểm thử. Xem các service cô lập tại docker/docker-compose.chain-access.yml.

3. Luồng dữ liệu

Dữ liệu chi tiết được lưu trữ tại Sub-Chain. Merkle root và proof block có chữ ký được neo lên Main Chain. Nhánh ZK tùy chọn trong luồng thiết kế này chỉ có triển khai mock:

graph TD
    subgraph "Sub-Chain (Logistics/Finance/...)"
        A[Business Events] --> B[Ordering Service]
        B --> C[Block Builder]
        C --> D[(Local DB)]
        C --> E[Merkle Tree / ZK Prover]
    end

    subgraph "Main Chain (Root Authority)"
        F[ZK Verifier] --> G[Proof Storage]
        G --> H[(Global Integrity State)]
    end

    E -- "Submit Proof (Hash + ZKP)" --> F

    subgraph "Hierarchy Manager"
        I[Transaction Manager 2PC]
    end

    I -. "Coordinate" .-> A

4. Thao tác liên chuỗi (2PC)

Coordinator chiếm quyền ghi journal khi được dùng lần đầu. Manager chỉ dùng registry/channel có thể chia sẻ SQL registry mà không mở writer 2PC nếu chưa có lịch sử coordinator. Lịch sử data/transactions đã tồn tại được khôi phục lúc startup và giữ lease độc quyền. Đường dẫn journal 2PC hoặc SubChain dùng chung vẫn cần một writer sở hữu; khả năng ghi registry đồng thời không cung cấp nhiều writer ordering/coordinator.

Gọi HierarchyManager.close() khi chủ sở hữu kết thúc. Hàm đóng orderer của sub-chain, coordinator đã mở và storage mà không tạo journal chưa dùng. SubChain.stop() xử lý các block đã commit rồi giải phóng orderer và lease, cho phép instance thay thế khôi phục cùng đường dẫn. Validation entity theo dõi operation và status riêng cho từng chain.

CrossChainTransactionManager trong hierachain/hierarchical/transaction_manager.py triển khai giao thức Two-Phase Commit để duy trì tính nguyên tử qua các Sub-Chain:

ACK pha của coordinator và ACK commit của participant vẫn yêu cầu đọc lại journal bền vững. Journal gốc dùng read_since(cursor) để decode record mới sau lượt quét lịch sử đầu tiên, kể cả record trong file đã rotate. Participant thử lại giữ ID event bền vững để tránh ghi trùng; submission không rõ kết quả làm mất hiệu lực snapshot marker. Journal tùy chỉnh chỉ có replay() tiếp tục dùng replay toàn bộ. Lịch sử transaction và số archive vẫn chưa có giới hạn; thay đổi này không thêm retention hay compaction.

from hierachain.hierarchical.hierarchy_manager import HierarchyManager

manager = HierarchyManager()
tx_id = manager.initiate_cross_chain_transaction(
    source_chain_name="supply_chain",
    dest_chain_name="finance_chain",
    payload={"asset_id": "INV-100", "action": "settle_payment"}
)

5. Tính riêng tư và xác thực zero-knowledge

• Xác thực Main Chain: Proof block có chữ ký và điểm neo Merkle là luồng toàn vẹn đã triển khai. Proof ZK mock không chứng minh tính đúng đắn của bước chuyển trạng thái hay tính riêng tư zero-knowledge; ZK production chưa khả dụng.
• Bộ sưu tập dữ liệu riêng tư: Thư viện cung cấp payload mã hóa trong bộ nhớ và kiểm tra tổ chức. Ứng dụng phải tích hợp lưu bền vững và neo hash; ghi qua REST chưa triển khai.

Liên quan

• Consensus Module
• Domains Module
• Hướng dẫn Two-Phase Commit

Projection entity và root của proof

Sub-Chain khởi tạo WorldState từ genesis cục bộ trước khi đồng bộ startup. Rehydration xóa projection và áp dụng lịch sử đã persist đúng một lần; đồng bộ lặp lại với tip không đổi không tăng event count của entity.

WorldState.get_state_root() băm projection entity hiện tại để phục vụ chẩn đoán. Metadata proof liên cấp và public inputs ZK dùng Merkle root của event trong block: root block trước và root block mới nhất (hoặc fallback genesis/hash hiện có tại vị trí tương ứng). Vì vậy anchor giữ contract về event trong block, không phải root projection entity. Thay đổi commitment này cần migration riêng cho schema proof và verifier.