> ## Documentation Index
> Fetch the complete documentation index at: https://docs.labtrace.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Blockchain Service
> Understanding the blockchain transactions that power Labtrace operations
# 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:
Initialize new projects with blockchain identity and access control
Add users to projects with specific roles and permissions
Remove user access from projects with audit trail
Record file storage and metadata on the blockchain
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_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_CREATION_FUNDING` - Fund new user accounts
* `USER_ESCROW_OPT_IN` - Opt user into credits system
* `USER_CREDITS_ASSET_TRANSFER` - Transfer credits to users
* `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
* `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
* `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
```teal theme={null}
// 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