Skip to main content

​
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:
  1. Transactions are created and stored with CREATED status
  2. Periodic job sends transactions to Algorand network
  3. Status updates to SENT when successfully submitted
  4. Confirmation monitoring checks for blockchain inclusion
  5. Status updates to CONFIRMED with timestamp when included
  6. Saga continuation triggered by confirmation events