TELA Version Upgrades & Changes

Complete guide to upgrading TELA applications, managing versions, and handling breaking changes across the DERO ecosystem.

⬆️

Update Strategy: TELA's immutable smart contract system means "upgrading" creates new versions while preserving all historical states on the blockchain.

What You'll Learn

This tutorial covers TELA version management:

✅ Understanding TELA's commit-based versioning
✅ Updating INDEX manifests and DOC files
✅ Accessing historical versions via commit TXIDs
✅ Handling breaking changes in DERO, TELA-CLI, and XSWD
✅ Rolling back to previous versions

Estimated Time: 30-45 minutes

Experience Level: Intermediate (requires TELA deployment experience)

Understanding TELA Versioning

Version System

TELA applications use a commit-based versioning system:

TELA-INDEX-1 (Mutable)
├── Initial Deploy: SCID (permanent identifier)
├── Update 1: TXID_1 (first update transaction)
├── Update 2: TXID_2 (second update transaction)
└── Update N: TXID_N (latest version)

TELA-DOC-1 (Immutable)
└── Single deployment: SCID (never changes)

Key Concepts:

SCID: Smart Contract ID - permanent identifier (never changes)
TXID: Transaction ID - identifies specific version/update
TELA-INDEX-1: Updateable manifest (mutable, if deployed with ringsize 2)
TELA-DOC-1: Immutable files (permanent, cannot be changed)

🔒

Immutability Rule: INDEX contracts deployed with ringsize greater than 2 (anonymous deployment) are permanently immutable and cannot be updated. Only ringsize 2 (public deployment) allows the owner to update the contract.

How Version Tracking Works

TELA-INDEX-1 smart contracts track updates using blockchain variables:

// From TELA-INDEX-1.bas smart contract:
 
// Initial deployment (init function):
STORE("commit", 0)           // Commit counter starts at 0
STORE(0, HEX(TXID()))       // Store initial TXID at key "0"
STORE("hash", HEX(TXID()))  // Current hash
 
// Each update (UpdateCode function):
STORE("commit", LOAD("commit")+1)      // Increment: 0→1, 1→2, 2→3...
STORE(LOAD("commit"), HEX(TXID()))     // Store update TXID at key "1", "2", "3"...
STORE("hash", HEX(TXID()))             // Update current hash

Reading Version History:

» search scid vars YOUR_INDEX_SCID
# Returns:
# {"commit", "3"}        ← 3 updates have been made
# {"0", "abc123..."}     ← Initial deployment TXID
# {"1", "def456..."}     ← First update TXID
# {"2", "ghi789..."}     ← Second update TXID  
# {"3", "jkl012..."}     ← Third update TXID (latest)
# {"hash", "jkl012..."}  ← Current/latest commit hash

Version Tracking

# Serve current/latest version
» serve YOUR_SCID
 
# Clone current version to local files
» clone YOUR_SCID
 
# Clone specific version/commit
» clone YOUR_SCID@COMMIT_TXID
 
# View version history and commit hashes
» search scid vars YOUR_SCID
# Look for: "commit" (number of updates), "0", "1", "2"... (commit TXIDs), "hash" (latest)

Version Access: TELA-CLI's clone command with @txid syntax is how you access specific versions. The serve command always serves the latest version (or blocks updates if updates false is set).

TELA-CLI Updates Setting

TELA-CLI has a critical setting that controls whether updated content can be accessed:

# Check current setting
» info
# Look for: "Updated content allowed: true/false"
 
# Allow serving/cloning updated content
» updates true
 
# Block serving/cloning updated content (safety mode)
» updates false

Why This Matters:

Security: If updates false, TELA-CLI will refuse to serve/clone any INDEX that has been updated since you first accessed it
Safety: Protects you from serving malicious updates without your knowledge
Testing: Set updates true when intentionally testing new versions
Default: updates false for security

Example Error:

» clone abc123...
ERROR: user defined no updates and content has been updated
# Solution: » updates true (if you trust the update)

Upgrade Scenarios

Scenario 1: Update Application Content

When to Use:

Bug fixes in your application
New features or UI improvements
Content updates
Performance optimizations

Process:

# Step 1: Clone current version
» clone YOUR_INDEX_SCID
# Files saved to datashards/clone/<dURL>/
 
# Step 2: Modify files
# Navigate to cloned directory and edit files
# Example: datashards/clone/myapp.tela/index.html
 
# Step 3: Deploy updated DOC
» install-doc
Enter DOC file path » datashards/clone/myapp.tela/index.html
Enter DOC description » Updated version with bug fixes
Enter DOC icon » (leave empty or add icon URL)
Enter DOC dURL » myapp.tela
Enter DOC subDir » (leave empty)
Compress file data (y/n) » y
Enter DOC install ringsize » 2
# TELA-CLI returns: DOC install TXID: abc123...
# This TXID is your new DOC_SCID
 
# Step 4: Update INDEX with new DOC
» update-index YOUR_INDEX_SCID
Confirm password » ****
How many total documents are embedded in this INDEX? » 1
Enter DOC1 SCID » abc123...  # TXID from step 3
Add SC TELA-MODs (y/n) » n
Confirm INDEX update (y/n) » y
# TELA-CLI returns: INDEX update TXID: def456...
 
# Step 5: Verify update
» updates true  # Allow serving updated content
» serve YOUR_INDEX_SCID  # Serves latest version

Scenario 2: Add New Files

When to Use:

Adding new pages or modules
Expanding application functionality
Adding new resources

Process:

# Step 1: Deploy new DOC contracts
» install-doc
Enter DOC file path » /path/to/new-feature.js
Enter DOC description » New feature module
Enter DOC icon » 
Enter DOC dURL » myapp.tela
Enter DOC subDir » 
Compress file data (y/n) » y
Enter DOC install ringsize » 2
# TELA-CLI returns: DOC install TXID: xyz789...
 
# Step 2: Update INDEX to include new DOC
» update-index YOUR_INDEX_SCID
Confirm password » ****
How many total documents are embedded in this INDEX? » 3  # Increased from 2
Enter DOC1 SCID » abc123...  # Existing DOC 1
# File: index.html
# Author: deto1qy...
Enter DOC2 SCID » def456...  # Existing DOC 2
# File: style.css
# Author: deto1qy...
Enter DOC3 SCID » xyz789...  # New DOC from step 1
# File: new-feature.js
# Author: deto1qy...
Add SC TELA-MODs (y/n) » n
Confirm INDEX update (y/n) » y
# TELA-CLI returns: INDEX update TXID: new_txid...
 
# INDEX now references 3 DOCs

Pro Tip: TELA-CLI shows you the file name and author for each DOC SCID you enter, helping you verify you're adding the correct files.

Scenario 3: Remove Deprecated Files

When to Use:

Removing unused code or assets
Simplifying application structure
Deprecating old features

Process:

# Simply omit deprecated DOC from INDEX update
» update-index YOUR_INDEX_SCID
Confirm password » ****
How many total documents are embedded in this INDEX? » 2  # Reduced from 3
Enter DOC1 SCID » abc123...  # Keep this one
# File: index.html
Enter DOC2 SCID » def456...  # Keep this one
# File: style.css
# DOC3 (xyz789...) is no longer referenced
Add SC TELA-MODs (y/n) » n
Confirm INDEX update (y/n) » y

Important: The removed DOC smart contract still exists on the blockchain and can be accessed by its SCID. It's just no longer referenced by your INDEX. This is how TELA maintains permanent history!

Scenario 4: Update Metadata Only

When to Use:

Change application name or description
Update icon URL
Add/modify TELA-MODs

Process:

» update-index YOUR_INDEX_SCID
Confirm password » ****
How many total documents are embedded in this INDEX? » 2  # Keep same count
Enter DOC1 SCID » abc123...  # Same DOCs as before
Enter DOC2 SCID » def456...  # No code changes
Add SC TELA-MODs (y/n) » y  # To modify MODs
# Follow MOD prompts...
Confirm INDEX update (y/n) » y

⚠️

Metadata via TELA-MODs: To update name, description, or icon after deployment, you need to:

Deploy INDEX with TELA-MOD-1 (variable store MOD like vsoo)
Use set-var command to update var_header_name, var_header_description, or var_header_icon

Metadata set during InitializePrivate() cannot be changed without redeploying!

Update Individual Headers:

# Set var_header_name (requires vsoo or similar MOD)
» set-var YOUR_INDEX_SCID
Enter key to store » header_name
Enter value for key "header_name" » New App Name v2.0
 
# Update icon
» set-var YOUR_INDEX_SCID  
Enter key to store » header_icon
Enter value for key "header_icon" » https://new-icon.url

Breaking Changes

DERO Network Updates

Blockchain Protocol Changes

Impact: Changes to DERO core consensus or RPC methods

Example: New RPC Method Signature

// Before (old version)
xswd.call('DERO.GetInfo')  // Returns basic info
 
// After (updated version)
xswd.call('DERO.GetInfo')  // Returns extended info with new fields

Handling:

// Defensive programming for version compatibility
async function getNetworkInfo() {
    try {
        const info = await xswd.call('DERO.GetInfo');
        
        // Check for new fields before using
        const height = info.height || info.topoheight || 0;
        const difficulty = info.difficulty || 0;
        
        // Use optional chaining for safety
        const miners = info.network_active_miners ?? 'N/A';
        
        return { height, difficulty, miners };
    } catch (error) {
        console.error('GetInfo failed:', error);
        return null;
    }
}

Smart Contract Changes

Impact: Changes to TELA standard contracts

Example: TELA-MOD-1 Update

// Old MOD
Function SetVar(key String, value String) ...
 
// New MOD (with validation)
Function SetVar(key String, value String, signature String) ...

Handling:

// Check MOD version before calling
async function setVariable(scid, key, value) {
    const scInfo = await xswd.call('DERO.GetSC', [{
        scid: scid,
        code: true,
        variables: false
    }]);
    
    // Check if signature parameter exists in smart contract code
    const needsSignature = scInfo.code.includes('signature String');
    
    const sc_rpc = [
        { name: "entrypoint", datatype: "S", value: "SetVar" },
        { name: "k", datatype: "S", value: key },
        { name: "v", datatype: "S", value: value }
    ];
    
    if (needsSignature) {
        sc_rpc.push({ name: "signature", datatype: "S", value: generateSig() });
    }
    
    return await xswd.call('sctransfer', [{
        scid: scid,
        sc_rpc: sc_rpc,
        ringsize: 2
    }]);
}

Note: TELA-MOD-1 SetVar uses parameters k and v, not key and value.

XSWD Protocol Updates

Connection Changes

For production XSWD implementations, use XSWD Advanced or XSWD Basic which handle version compatibility automatically.

XSWD Handshake Format (Current)

// Application data sent on connection
const applicationData = {
    id: "unique-app-id-" + Date.now(),
    name: "Your Application Name",
    description: "App description",
    url: "http://localhost:" + location.port  // Must match origin
};
 
// Connection flow (use localhost to match app1 pattern)
const socket = new WebSocket("ws://localhost:44326/xswd");
socket.addEventListener("open", (event) => {
    socket.send(JSON.stringify(applicationData));
});
 
socket.addEventListener("message", (event) => {
    const response = JSON.parse(event.data);
    if (response.accepted) {
        // Connection accepted, can make RPC calls
        console.log("XSWD connected:", response.message);
    }
});

Version Compatibility: XSWD handshake format has been stable since initial release. Always verify against DERO source (opens in a new tab) for latest specifications.

TELA-CLI Updates

Command Changes

Example: install-doc Parameter Updates

# Old version
» install-doc
Enter DOC file path » /path/to/file.html
Enter DOC description » Description
# Fixed compression behavior
 
# New version
» install-doc
Enter DOC file path » /path/to/file.html
Enter DOC description » Description
Compress file data (y/n) » y  # New prompt
Enter compression level (1-9) » 6  # New option

Handling:

# Check TELA-CLI version
./tela-cli --version
 
# Read changelog before updating
cat CHANGELOG.md
 
# Test on testnet before mainnet
./tela-cli --daemon=127.0.0.1:40402

Checking Compatibility

⚠️

Always test on testnet first! Version updates can introduce breaking changes. Verify compatibility before mainnet deployment.

Check version compatibility before deploying:

# Check TELA package version (in Go package)
# See: https://github.com/civilware/tela/blob/main/tela.go
# Current: v1.0.0
 
# Check TELA-CLI available commands
./tela-cli
» help
 
# Check your INDEX smart contract version
» search scid vars YOUR_SCID
# Look for "telaVersion" variable (current: "1.1.0")
 
# Check DERO daemon version
# In derod terminal: version
# Or via XSWD: xswd.call('DERO.GetInfo')
 
# Read changelogs before updating
# TELA: https://github.com/civilware/tela/blob/main/CHANGELOG.md
# DERO: https://github.com/deroproject/derohe/blob/main/Changelog.md

Current Versions (as of documentation):

TELA Package: v1.0.0
TELA-INDEX-1: v1.1.0 (supports TELA-MOD-1)
TELA-DOC-1: v1.0.0

Migration Checklist

Before Upgrading

Backup current version
- Save all SCIDs and TXIDs
- Export application files
- Document current functionality
Review changelog
- Read DERO release notes
- Check TELA-CLI changelog
- Review XSWD updates
Test on testnet
- Deploy updates to testnet first
- Verify all functionality
- Check performance
Update dependencies
- Update TELA-CLI to latest
- Sync DERO daemon
- Update wallet software

During Upgrade

Deploy incrementally
- Update one DOC at a time
- Test after each update
- Monitor for errors
Maintain backward compatibility
- Keep old versions accessible
- Support multiple API versions if needed
- Provide migration path for users
Document changes
- Note new SCID/TXID pairs
- Update user documentation
- Communicate changes to users

After Upgrade

Verify functionality
- Test all features
- Check XSWD connectivity
- Validate blockchain calls
Monitor performance
- Check load times
- Verify data accuracy
- Monitor error rates
Update documentation
- Update README
- Revise user guides
- Update API documentation

Rollback Procedures

Reverting to Previous Version

How to Access Historical Versions: Use clone <scid>@<txid> to download specific commits. The serve command only serves the latest version.

# Step 1: Find the commit TXID you want to revert to
» search scid vars YOUR_SCID
# Look for numeric keys (0, 1, 2...) showing commit TXIDs
# Example output: {"commit", "3"}, {"0", "txid0"}, {"1", "txid1"}, {"2", "txid2"}, {"3", "txid3"}
 
# Step 2: Clone that specific version
» clone YOUR_SCID@PREVIOUS_TXID
# Files saved to datashards/clone/<dURL>/
 
# Step 3: Verify the cloned version is correct
# Check files in datashards/clone/<dURL>/
 
# Step 4: Re-deploy as new version (creates rollback)
# Deploy the old DOCs again
» install-doc datashards/clone/<dURL>/index.html
# Get new DOC_SCID
 
# Update INDEX to point to "old" DOCs (now with new SCIDs)
» update-index YOUR_SCID
# Enter the new DOC SCIDs from re-deployment

Result: Your INDEX now points to the old code, effectively rolling back while maintaining blockchain history.

Emergency Rollback

// Application-level version checking
const MINIMUM_VERSION = {
    dero: '5.2.0',
    xswd: 'v2'
};
 
async function checkCompatibility() {
    const info = await xswd.call('DERO.GetInfo');
    
    if (!info || !info.version) {
        alert('Unable to verify DERO version. Please update your daemon.');
        return false;
    }
    
    if (compareVersions(info.version, MINIMUM_VERSION.dero) < 0) {
        alert(`This application requires DERO ${MINIMUM_VERSION.dero}+`);
        return false;
    }
    
    return true;
}
 
// Show compatibility warning
window.addEventListener('load', async () => {
    const compatible = await checkCompatibility();
    if (!compatible) {
        document.body.innerHTML = '<h1>Upgrade Required</h1>';
    }
});

Best Practices

1. Semantic Versioning in Metadata

# Use version in INDEX name
» update-index
Enter INDEX name » MyApp v2.1.0
Enter INDEX description » Added feature X (v2.1.0)

2. Changelog in Application

<!-- Embed changelog in about section -->
<div id="changelog">
    <h3>Version History</h3>
    <ul>
        <li><strong>v2.1.0</strong> - Added dark mode</li>
        <li><strong>v2.0.0</strong> - Major redesign</li>
        <li><strong>v1.0.0</strong> - Initial release</li>
    </ul>
</div>

3. Version Detection

// Detect and display current version
const APP_VERSION = '2.1.0';
const DEPLOY_SCID = 'your-scid-here';
 
async function displayVersion() {
    try {
        const scInfo = await xswd.call('DERO.GetSC', [{
            scid: DEPLOY_SCID,
            variables: true,
            code: false
        }]);
        
        // TELA-INDEX stores commit count in "commit" variable
        // Commit TXIDs are stored as numeric keys: 0, 1, 2, 3...
        const commitCount = scInfo.valuesstring?.commit || 
                           scInfo.variablestringkeys?.commit || 0;
        
        document.getElementById('version').textContent = 
            `v${APP_VERSION} (${commitCount} updates)`;
    } catch (error) {
        console.error('Failed to get version:', error);
        document.getElementById('version').textContent = `v${APP_VERSION}`;
    }
}

How TELA Tracks Versions:

commit variable = Total number of updates (starts at 0)
Numeric keys (0, 1, 2, etc.) = TXID hash of each commit
hash variable = TXID of most recent update

4. Graceful Degradation

// Support multiple DERO versions
async function getBlockHeader(height) {
    try {
        // Try new method first
        return await xswd.call('DERO.GetBlockHeaderByHeight', [height]);
    } catch (e) {
        // Fallback to old method
        try {
            const block = await xswd.call('DERO.GetBlock', [height]);
            return block.block_header;
        } catch (e2) {
            console.error('Failed to get block header:', e2);
            return null;
        }
    }
}
 
// Defensive error handling for version compatibility
async function safeXSWDCall(method, params) {
    try {
        return await xswd.call(method, params);
    } catch (error) {
        console.warn(`${method} failed, may need update:`, error.message);
        return null;
    }
}

Resources

TELA Changelog DERO Changelog Migration Guide Error Troubleshooting

Getting Help

Upgrade issues? Get support:

Discord: Join community (opens in a new tab)
Forum: Post questions (opens in a new tab)
GitHub: Report bugs (opens in a new tab)

Pro Tip: Always test upgrades on testnet first. The blockchain is permanent - you can't undo a mainnet deployment!

Next Steps

🎓

Version Management Mastered! You now understand how to safely update and maintain TELA applications on the blockchain.

After mastering version management:

TELA Deployment: Read Best Practices for production deployment guide
Advanced Features: Explore DocShards for handling large applications
Security: Review Security Model to understand immutability guarantees
Community: Share your experience in Discord (opens in a new tab) or Forum (opens in a new tab)

Remember: Every update creates permanent blockchain history. Test thoroughly on testnet before mainnet deployment!