Blockchain Service

The blockchain service is a dedicated microservice that handles all interactions with the Algorand blockchain. It manages smart contracts, processes transactions, and maintains the immutable record of all platform operations.

Core Blockchain Operations

LabTrace performs five main types of blockchain transactions, each recorded permanently on the Algorand blockchain:

Project Creation

Initialize new projects with blockchain identity and access control

Project Invitations

Add users to projects with specific roles and permissions

Invitation Removal

Remove user access from projects with audit trail

File Upload

Record file storage and metadata on the blockchain

File Deletion

Mark files as deleted while preserving historical records

Transaction Types

The blockchain service implements complex multi-step operations called “sagas” rather than single transactions. Each major operation involves multiple Algorand transactions executed in sequence. The system supports 29 different transaction types across five main categories:

Transaction Categories

Project Management

PROJECT_FUNDING - Initial project account funding
PROJECT_ASSET_CREATION - Create project-specific Algorand Standard Asset (ASA)
PROJECT_CONTRACT_CREATION - Deploy public smart contract
PROJECT_PRIVATE_CONTRACT_CREATION - Deploy private smart contract
PROJECT_CREATION_CLAWBACK_CREDITS - Deduct credits for project creation

User Operations

USER_CREATION_FUNDING - Fund new user accounts
USER_ESCROW_OPT_IN - Opt user into credits system
USER_CREDITS_ASSET_TRANSFER - Transfer credits to users

Project Invitations

PROJECT_USER_ACCOUNT_FUNDING - Fund invited user account
PROJECT_INVITATION_FUNDING - Fund project for invitation
PROJECT_ASSET_OPT_IN - User opts into project asset
PROJECT_ASSET_TRANSFER - Transfer project tokens to user
PROJECT_APPLICATION_OPT_IN - User opts into public contract
PROJECT_PRIVATE_APPLICATION_OPT_IN - User opts into private contract
PROJECT_WHITELIST - Whitelist user in public contract
PROJECT_PRIVATE_WHITELIST - Whitelist user in private contract
PROJECT_INVITATION_CLAWBACK_CREDITS - Deduct credits for invitation

File Operations

PROJECT_FILE_UPLOAD_FUNDING - Fund user for file upload
PROJECT_FILE_UPLOAD - Record file on blockchain
PROJECT_FILE_DELETION_FUNDING - Fund user for file deletion
PROJECT_FILE_DELETION - Record file deletion on blockchain
FILE_UPLOAD_CLAWBACK_CREDITS - Deduct credits for upload
FILE_DELETION_CLAWBACK_CREDITS - Deduct credits for deletion

User Removal

PROJECT_USER_REMOVAL_FUNDING - Fund removal process
PROJECT_USER_REMOVAL_USER_FUNDING - Fund user account for removal
PROJECT_USER_REMOVAL_ASSET_CLAWBACK - Reclaim project tokens
PROJECT_USER_REMOVAL_PUBLIC_CLOSEOUT - Close out public contract
PROJECT_USER_REMOVAL_PRIVATE_CLOSEOUT - Close out private contract

1. Project Creation Saga

Project creation involves multiple sequential transactions: Step 1: Credits Deduction

Transaction Type: PROJECT_CREATION_CLAWBACK_CREDITS
Purpose: Deduct 50 credits from project creator
Amount: 50 credits

Step 2: Account Funding

Transaction Type: PROJECT_FUNDING
Purpose: Fund project multi-signature account
Amount: ~0.1 ALGO for transaction fees

Step 3: Asset Creation

Transaction Type: PROJECT_ASSET_CREATION
Purpose: Create project-specific Algorand Standard Asset
Details:
  - Asset name: "LT-{projectId}"
  - Total supply: 1000 units
  - Decimals: 0
  - Manager: Project multi-sig address

Step 4: Public Contract Deployment

Transaction Type: PROJECT_CONTRACT_CREATION
Purpose: Deploy public smart contract for file operations
Contract Features:
  - Whitelist management
  - File upload validation
  - Access control

Step 5: Private Contract Deployment

Transaction Type: PROJECT_PRIVATE_CONTRACT_CREATION
Purpose: Deploy private smart contract for sensitive files
Contract Features:
  - Enhanced access controls
  - Private file management
  - Stricter validation

2. Project Invitation Saga

Adding users to projects requires multiple blockchain operations: Step 1: Credits Deduction

Transaction Type: PROJECT_INVITATION_CLAWBACK_CREDITS
Purpose: Deduct 10 credits from project creator
Amount: 10 credits

Step 2: User Account Funding

Transaction Type: PROJECT_USER_ACCOUNT_FUNDING
Purpose: Fund invited user's account
Amount: ~0.36 ALGO (covers opt-in fees)

Step 3: Project Funding

Transaction Type: PROJECT_INVITATION_FUNDING
Purpose: Fund project account for invitation
Amount: 0.003 ALGO

Step 4: Asset Opt-In

Transaction Type: PROJECT_ASSET_OPT_IN
Purpose: User opts into project asset
Result: User can receive project tokens

Step 5: Asset Transfer

Transaction Type: PROJECT_ASSET_TRANSFER
Purpose: Transfer 1 project token to user
Amount: 1 project token

Step 6: Public Contract Opt-In

Transaction Type: PROJECT_APPLICATION_OPT_IN
Purpose: User opts into public smart contract
Result: User can interact with public files

Step 7: Public Whitelist

Transaction Type: PROJECT_WHITELIST
Purpose: Whitelist user in public contract
Application Call: "WHITELIST" with user address

Step 8: Private Contract Opt-In

Transaction Type: PROJECT_PRIVATE_APPLICATION_OPT_IN
Purpose: User opts into private smart contract
Result: User can interact with private files

Step 9: Private Whitelist

Transaction Type: PROJECT_PRIVATE_WHITELIST
Purpose: Whitelist user in private contract
Application Call: "WHITELIST" with user address

3. File Upload Saga

File uploads involve blockchain recording with IPFS integration: Step 1: Credits Deduction

Transaction Type: FILE_UPLOAD_CLAWBACK_CREDITS
Purpose: Deduct credits based on file size
Amount: 1 credit (private) or ceil(file_size) credits (public)

Step 2: Account Funding

Transaction Type: PROJECT_FILE_UPLOAD_FUNDING
Purpose: Fund user account for upload transaction
Amount: 0.001 ALGO

Step 3: File Upload Record

Transaction Type: PROJECT_FILE_UPLOAD
Purpose: Record file on blockchain
Application Call: "UPLOAD" with IPFS hash
Transaction Note: "CID: {ipfsHash} | Linked to: {linkedFiles}"
Smart Contract: Public or Private based on directory

What gets recorded:

IPFS content identifier (CID)
Linked file references
Upload timestamp
User authorization proof

4. File Deletion Saga

File deletions maintain audit trail while marking files as deleted: Step 1: Credits Deduction

Transaction Type: FILE_DELETION_CLAWBACK_CREDITS
Purpose: Deduct 1 credit for deletion
Amount: 1 credit

Step 2: Account Funding

Transaction Type: PROJECT_FILE_DELETION_FUNDING
Purpose: Fund user account for deletion transaction
Amount: 0.001 ALGO

Step 3: File Deletion Record

Transaction Type: PROJECT_FILE_DELETION
Purpose: Record file deletion on blockchain
Application Call: "UPLOAD" with original IPFS hash
Transaction Note: "Deletion reason: {reason} | CID: {ipfsHash}"
Smart Contract: Same contract where file was uploaded

What gets recorded:

Original file IPFS hash
Deletion reason
Deletion timestamp
User authorization proof

5. User Removal Saga

Removing users involves complex cleanup: Step 1: Project Funding

Transaction Type: PROJECT_USER_REMOVAL_FUNDING
Purpose: Fund project for removal operations

Step 2: User Funding

Transaction Type: PROJECT_USER_REMOVAL_USER_FUNDING
Purpose: Fund user account for removal transactions

Step 3: Asset Clawback

Transaction Type: PROJECT_USER_REMOVAL_ASSET_CLAWBACK
Purpose: Reclaim project tokens from user
Amount: All project tokens held by user

Step 4: Public Contract Closeout

Transaction Type: PROJECT_USER_REMOVAL_PUBLIC_CLOSEOUT
Purpose: Remove user from public smart contract
Result: User loses public file access

Step 5: Private Contract Closeout

Transaction Type: PROJECT_USER_REMOVAL_PRIVATE_CLOSEOUT
Purpose: Remove user from private smart contract
Result: User loses private file access

Smart Contract Details

Contract Structure

The system uses a single smart contract template deployed twice per project:

Public Contract: For general project files
Private Contract: For sensitive project files

Contract Operations

// Whitelist a user (only project creator)
txna ApplicationArgs 0 == "WHITELIST"
assert(txn.Sender == global.CreatorAddress)
app_local_put(1, "WHITELIST", 1)

// Upload a file (only whitelisted users)
txna ApplicationArgs 0 == "UPLOAD"
assert(app_local_get(0, "WHITELIST") == 1)
app_global_put("FILE_ID", txna ApplicationArgs 1)

Transaction Notes Format

Funding: LT-funding-{uuid}
File Upload: CID: {ipfsHash} | Linked to: {linkedFiles}
File Deletion: Deletion reason: {reason} | CID: {ipfsHash}
Whitelist: {uuid}

Transaction Monitoring

The system continuously monitors all transactions through multiple states: Transaction States:

CREATED - Transaction prepared but not sent
SENT - Transaction submitted to network
CONFIRMED - Transaction confirmed on blockchain
EXPIRED - Transaction expired without confirmation
ERROR - Transaction failed

Monitoring Process:

Transactions are created and stored with CREATED status
Periodic job sends transactions to Algorand network
Status updates to SENT when successfully submitted
Confirmation monitoring checks for blockchain inclusion
Status updates to CONFIRMED with timestamp when included
Saga continuation triggered by confirmation events

Get Started

Core Concepts

Blockchain Service

Blockchain Service

Core Blockchain Operations

Project Creation

Project Invitations

Invitation Removal

File Upload

File Deletion

Transaction Types

Transaction Categories

Project Management

User Operations

Project Invitations

File Operations

User Removal

1. Project Creation Saga

2. Project Invitation Saga

3. File Upload Saga

4. File Deletion Saga

5. User Removal Saga

Smart Contract Details

Contract Structure

Contract Operations

Transaction Notes Format

Transaction Monitoring

​Blockchain Service

​Core Blockchain Operations

Project Creation

Project Invitations

Invitation Removal

File Upload

File Deletion

​Transaction Types

​Transaction Categories

Project Management

User Operations

Project Invitations

File Operations

User Removal

​1. Project Creation Saga

​2. Project Invitation Saga

​3. File Upload Saga

​4. File Deletion Saga

​5. User Removal Saga

​Smart Contract Details

​Contract Structure

​Contract Operations

​Transaction Notes Format

​Transaction Monitoring

Blockchain Service

Core Blockchain Operations

Transaction Types

Transaction Categories

1. Project Creation Saga

2. Project Invitation Saga

3. File Upload Saga

4. File Deletion Saga

5. User Removal Saga

Smart Contract Details

Contract Structure

Contract Operations

Transaction Notes Format

Transaction Monitoring