Smart Contracts Toolkit (SCT)

At a Glance

• Category: Planning, Design & Assessment
• Primary environment: MaaS Consumer, MaaS Provider
• Documentation focus: Design reference
• Maturity: TRL 3 (first release, M18)
• Related architecture docs: Reference Architecture Guide, Environments

Purpose

The Smart Contract Toolkit (SCT) is designed as an integral solution that operates on top of the MaaS blockchain infrastructure. Its primary components include the blockchain network itself, a suite of smart contracts, and digital wallets that manage identity and user interactions. Together, these elements form the backbone of a decentralized application layer capable of managing logic, data integrity, and secure multi-stakeholder interaction.

Primary Actors

The D5.2 usage viewpoint defines roles, permissions, constraints, a role-task matrix, and a use case diagram for this solution.

• Regular User: Initiate service requests; consult contract/production status exposed by smart contracts; constraint: Limited to their own requests/transactions and to permitted contract functions
• Power User: Operational/supervisory actions (approve/authorize requests, confirm completion) according to contract conditions; constraint: Cannot change governance parameters or administrative settings of the toolkit
• Administrator: Contract lifecycle oversight (deployment, versioning, access policies), user/role administration within the toolkit; auditing and governance operations supported by the toolkit; constraint: Subject to governance rules (separation of duties if enforced)

Smart-contract interaction use-case diagram extracted from MaaSAI deliverable D5.2.

Functional Components

SCT combines smart-contract definitions, deployment services, wallet-based identity, and blockchain interaction APIs. The functional view shows how contract operations are routed from external applications through the toolkit into the blockchain layer and back toward solution APIs.

Smart-contract functional interaction diagram extracted from MaaSAI deliverable D5.2.

Design Baseline

The MaaS blockchain serves as the trusted execution environment for the toolkit, providing a secure and immutable ledger to record contract state and transactions. The smart contracts themselves are modular and designed to encapsulate key workflows — such as role management, order processing, and delivery tracking — with clear logic and access control. These contracts act as autonomous programs that execute once specific conditions are met, without requiring further intervention.

Digital wallets are again central to the system’s interaction model, functioning as secure identity holders and signature tools. Each user of the toolkit interacts with the blockchain through a wallet, whether to initiate contract functions, check order status, or authenticate their role within the system.

The Smart Contracts Toolkit (SCT) provides the execution environment and supporting services for lifecycle management of smart contracts within the MaaSAI blockchain ecosystem. Contract definitions are written in Solidity and compiled using the Solidity compiler, producing bytecode and ABI files. These are deployed to the blockchain network—typically a Hyperledger Besu (EVM-compatible) node—via Web3 libraries over authenticated HTTP RPC endpoints.

Once deployed, the SCT manages contract invocation, event listening, and state synchronization. Transactions are signed locally using the user’s private key and transmitted through secure RPC connections to the blockchain node, where consensus (PoA) finalizes and records them immutably. The SCT backend exposes RESTful and WebSocket APIs for integration with external applications, enabling off-chain systems to query contract states, trigger methods, and receive asynchronous event updates.

Architecture diagram extracted from MaaSAI deliverable D5.2.

Technology Stack

The SCT is implemented as a Python-based blockchain middleware service with a React frontend.

Category	Technology
Backend	Python (> 3.11) with FastAPI and Uvicorn for the REST API; Pydantic v2 for request/response schema validation; PyJWT for JWT token issuance and validation
Blockchain	Web3.py (7.x) for Ethereum-compatible interaction (transaction signing, ABI encoding, receipt handling); smart contracts written in Solidity (8.x)
Frontend	React management UI for agreement lifecycle and role administration (under development)
Security	Keycloak for authentication and identity management
Containerisation	Docker with Docker Compose

Integrations & External Dependencies

The SCT is the bridge between marketplace services and the distributed ledger. It receives finalised agreements and business events from the Cloud MaaS Marketplace (CMM) through a webhook interface and propagates them as signed transactions to the MaaS Blockchain (MSB), where the Solidity smart contract suite is deployed. Keycloak, currently deployed as the identity provider for the MaaSAI UI, issues JWTs carrying the user’s blockchain wallet address as a claim; full project-level integration is underway. The target blockchain network is cloud-hosted and accessed remotely over HTTPS, so no local blockchain infrastructure is required.

APIs & Interfaces

The REST API is documented through a Swagger UI and covers:

• POST /api/auth/register, POST /api/auth/login — user registration with server-side Ethereum wallet generation, and JWT Bearer token issuance
• POST /api/webhook-decoded, GET /api/webhook-decoded/events — ingest marketplace business events as signed on-chain transactions and query the session event log
• GET /api/contract/read/{function}, POST /api/contract/write/{function} — read-only contract queries and state-changing calls signed with the user’s key
• GET /api/contract/functions — list deployed contract functions with signatures and mutability
• GET /health — API status and live blockchain connectivity check

The web dashboard lets users monitor blockchain-recorded agreements and inspect their details, while administrators can grant or revoke rights and modify agreements. Transaction hashes, block numbers, wallets and gas fees are abstracted from end users.

User Interface

SCT is consumed through its documented API; the figures below show the Swagger interface and the end-to-end workflow:

Swagger documentation of the SCT API — MaaSAI deliverable D12.1.

End-to-end workflow cycle of the SCT — MaaSAI deliverable D12.1.

Deployment & Configuration

The SCT is a lightweight, stateless containerised service deployed with Docker Compose; in the full MaaSAI stack it shares the Compose network with the UI backend and Keycloak services. The Smart Contract Suite itself is deployed within the MaaS Blockchain toolkit. Computational requirements are modest:

Requirement	Minimum	Recommended
CPU	1 vCPU	2 vCPU
RAM	4 GB	8 GB
Storage	1 GB	5 GB
OS	64-bit Linux or Windows Server 2022	64-bit Linux or Windows Server 2022