TELA-INDEX-1 Specification

Complete technical specification for TELA-INDEX-1 smart contracts - the manifest standard that ties TELA applications together.

📋

What is TELA-INDEX-1? A smart contract that serves as the entrypoint for TELA applications. It references all DOC contracts (files) and provides updateable metadata for your application.

Overview

TELA-INDEX-1 contracts serve as the "package.json" or "manifest" for TELA applications. Users enter a single INDEX SCID to access the entire application.

Key Characteristics

Property	Value
Mutability	✏️ Updateable (if deployed with ringsize 2)
Purpose	Application manifest and entrypoint
References	Lists all DOC contract SCIDs
Versioning	Built-in commit system tracks updates
Max Size	Variable (see size limits below)
MOD Support	Can integrate TELA-MOD-1 extensions

Size Limitations

📏

Critical Size Constraints

INDEX size directly impacts updateability and capacity.

Size Limits (from source code)

Limit	Size	Purpose
Maximum Installation	11.64 KB	MAX_INDEX_INSTALL_SIZE
Recommended for Updates	9 KB	Ensures room for future updates
Maximum Practical	~11 KB	Absolute deployment limit

Capacity Estimates

INDEX Size	DOC Capacity	Updateable?
< 9 KB	~90 DOCs	✅ Yes (room for growth)
9-11 KB	~100-120 DOCs	⚠️ Limited update capacity
> 11.64 KB	N/A	❌ Cannot deploy

Testing Results (from source):

~90 DOCs: Reliable updates, can add more later
~120 DOCs: Maximum capacity, may not accept additional DOCs in updates

Size Management: Use DocShards and Libraries to include more content without bloating INDEX size. Each SCID reference is ~64 bytes.

Smart Contract Structure

TELA-INDEX-1 Template

Function InitializePrivate() Uint64
10 IF EXISTS("nameHdr") THEN GOTO 100
 
// Header information (lines 30-33)
30 STORE("var_header_name", "App Name")
31 STORE("var_header_description", "A TELA App")
32 STORE("var_header_icon", "https://example.com/icon-100x100.png")
33 STORE("dURL", "app.tela")
 
// TELA-MOD-1 tags (optional, line 34)
34 STORE("mods", "")  // Example: "vsoo,txdwd"
 
// DOC references (lines 40+)
40 STORE("DOC1", "a891299086d218840d1eb71ae759ddc08f1e85cbf35801cc34ef64b4b07939c9")
41 STORE("DOC2", "b891299086d218840d1eb71ae759ddc08f1e85cbf35801cc34ef64b4b07939c8")
// Add more DOCs as needed:
// 42 STORE("DOC3", "c891299086d218840d1eb71ae759ddc08f1e85cbf35801cc34ef64b4b07939c7")
// 43 STORE("DOC4", "d891299086d218840d1eb71ae759ddc08f1e85cbf35801cc34ef64b4b07939c6")
 
// Version tracking initialization
90 STORE("commit", 0)
91 STORE(0, HEX(TXID()))
92 STORE("hash", HEX(TXID()))
 
100 RETURN 0
End Function

Contract Variables

Variable	Type	Required	Description
`var_header_name`	String	Yes	Application name
`var_header_description`	String	No	App description
`var_header_icon`	String	No	Icon URL or SCID (100x100px)
`dURL`	String	Yes	Unique app identifier (e.g., "myapp.tela")
`mods`	String	No	Comma-separated MOD tags (e.g., "vsoo,txdwd")
`DOC1`	String	Yes	Entrypoint DOC SCID (minimum requirement)
`DOC2...DOCn`	String	No	Additional DOC SCIDs
`commit`	Uint64	Auto	Version counter (0, 1, 2, 3...)
`0, 1, 2...`	String	Auto	Commit TXID history
`hash`	String	Auto	Current commit hash

Smart Contract Functions

InitializePrivate()

Purpose: Initialize contract on deployment

Called: Once, automatically at deployment

Actions:

Stores application metadata
Stores all DOC references
Initializes version tracking
Sets up MOD integration (if specified)

Cannot be modified after deployment (immutable initialization)

UpdateCode(mods String, code String)

Purpose: Update INDEX contract with new configuration

Parameters:

mods (String) - MOD tags to enable/disable
code (String) - New smart contract code

Access: Contract owner only

Actions:

Increments commit counter
Stores update TXID
Updates hash to current TXID
Deploys new contract code

Version Tracking:

// Before update (commit 0):
STORE("commit", 0)
STORE(0, "abc123...")  // Initial TXID
STORE("hash", "abc123...")
 
// After first update (commit 1):
STORE("commit", 1)
STORE(0, "abc123...")  // Still there (history)
STORE(1, "def456...")  // First update TXID
STORE("hash", "def456...")  // Updated
 
// After second update (commit 2):
STORE("commit", 2)
STORE(0, "abc123...")  // History preserved
STORE(1, "def456...")  // History preserved
STORE(2, "ghi789...")  // Second update TXID
STORE("hash", "ghi789...")  // Updated

📜

Complete History: Every update is preserved on the blockchain. Users can access any historical version using commit TXIDs.

Rate(r Uint64)

Purpose: Rate the INDEX contract quality

Parameters:

r (Uint64) - Rating value (0-99)

Access: Public - any wallet can rate

Effect:

Stores rating from calling wallet
One rating per wallet per contract
Updates overall rating statistics

Updateability & Immutability

Update Rules

Deployment Type	Ringsize	Updateable?
Public Deployment	2	✅ Yes - owner can update
Anonymous Deployment	> 2	❌ No - permanently immutable

🔒

Critical: Once deployed with ringsize > 2, the INDEX is permanently immutable. Choose wisely during deployment!

What Can Be Updated

Via UpdateCode:

✅ DOC references (add/remove/change DOCs)
✅ Application metadata (name, description, icon)
✅ MOD configuration (add/remove MODs)
✅ dURL identifier
❌ Contract SCID (this never changes)
❌ Contract owner (without Transfer Ownership MOD)

Via SetVar (with MOD):

✅ Dynamic variables (var_*)
✅ Custom metadata (var_meta_*)
✅ Owner notes (var_owners_note)
❌ Does NOT create new commit version

UpdateCode vs SetVar

Operation	Creates Commit?	Use Case
UpdateCode	✅ Yes	Code changes, DOC updates, major versions
SetVar	❌ No	Dynamic data, metadata updates, minor tweaks

Example:

# Major update - adds to version history
» update-index your-scid
# Creates commit 1, 2, 3...
 
# Minor update - doesn't create version
» set-var your-scid
Enter key » var_owners_note
Enter value » App is temporarily offline for maintenance
# Doesn't create new commit

TELA-MOD-1 Integration

INDEX contracts can integrate TELA-MOD-1 modules for extended functionality.

MODs Field

34 STORE("mods", "vsoo,txdwd,txto")

Format: Comma-separated MOD tags

Available MODs:

Variable Store: vsoo, vsooim, vspubsu, vspubow, vspubim
Transfers: txdwd, txdwa, txto

MODs at Deployment

» install-index
# ... standard prompts ...
Enter INDEX mods (comma separated tags, or leave blank) » vsoo,txdwd

MODs in Updates

» update-index your-scid
# ... update prompts ...
Add SC TELA-MODs (y/n) » y
Enter MODs to add » txto
Enter MODs to remove »

Learn more: TELA-MOD-1 Documentation

Deployment Procedures

Using TELA-CLI (Recommended)

» install-index
Confirm password » ****
Enter INDEX name » My TELA Application
Enter INDEX description » A decentralized web app
Enter INDEX icon » https://example.com/icon.png
Enter INDEX dURL » myapp.tela
How many total documents are embedded in this INDEX? » 3
Enter DOC1 SCID » abc123...  # Entrypoint (required)
# File: index.html
Enter DOC2 SCID » def456...
# File: style.css
Enter DOC3 SCID » ghi789...
# File: app.js
Enter INDEX mods (comma separated tags, or leave blank) » 
Enter INDEX install ringsize » 2
Confirm INDEX install (y/n) » y
 
# Output: INDEX install TXID: xyz123...

Manual Deployment (Advanced)

Step 1: Prepare TELA-INDEX-1.bas

Edit the template with your values:

30 STORE("var_header_name", "My App")
31 STORE("var_header_description", "My TELA application")
32 STORE("var_header_icon", "https://example.com/icon.png")
33 STORE("dURL", "myapp.tela")
34 STORE("mods", "vsoo,txdwd")
40 STORE("DOC1", "abc123...")  // Your deployed DOC SCIDs
41 STORE("DOC2", "def456...")
42 STORE("DOC3", "ghi789...")
90 STORE("commit", 0)
91 STORE(0, HEX(TXID()))
92 STORE("hash", HEX(TXID()))

Step 2: Deploy

curl --request POST --data-binary @TELA-INDEX-1.bas http://127.0.0.1:30000/install_sc

Update Procedures

Update INDEX with TELA-CLI

» update-index your-index-scid
Confirm password » ****
Enter INDEX name » My App v2.0  # Updated name
Enter INDEX description » [keep current or update]
Enter INDEX icon » [keep current or update]
Enter INDEX dURL » myapp.tela  # Usually keep same
How many total documents? » 4  # Adding 1 more DOC
Enter DOC1 SCID » abc123...  # Entrypoint
Enter DOC2 SCID » def456...  # Existing
Enter DOC3 SCID » ghi789...  # Existing
Enter DOC4 SCID » jkl012...  # NEW DOC
Add SC TELA-MODs (y/n) » n
Enter INDEX update ringsize » 2
Confirm INDEX update (y/n) » y

Manual Update (Advanced)

GetGasEstimate:

curl -X POST http://127.0.0.1:20000/json_rpc \
  -H 'content-type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "DERO.GetGasEstimate",
    "params": {
        "transfers": [],
        "signer": "deto1qyre7td6x9r88y4cavdgpv6k7lvx6j39lfsx420hpvh3ydpcrtxrxqg8v8e3z",
        "sc_rpc": [
            {
                "name": "SC_ACTION",
                "datatype": "U",
                "value": 0
            },
            {
                "name": "SC_ID",
                "datatype": "H",
                "value": "your-index-scid"
            },
            {
                "name": "entrypoint",
                "datatype": "S",
                "value": "UpdateCode"
            },
            {
                "name": "mods",
                "datatype": "S",
                "value": "vsoo,txdwd"
            },
            {
                "name": "code",
                "datatype": "S",
                "value": "NEW_TELA_INDEX_SC_CODE_GOES_HERE"
            }
        ]
    }
}'

Execute Update Transaction:

curl -X POST http://127.0.0.1:30000/json_rpc \
    -H 'content-type: application/json' \
    -d '{
    "jsonrpc": "2.0",
    "id": "0",
    "method": "Transfer",
    "params": {
        "ringsize": 2,
        "fees": 320,
        "sc_rpc": [
            {
                "name": "entrypoint",
                "datatype": "S",
                "value": "UpdateCode"
            },
            {
                "name": "mods",
                "datatype": "S",
                "value": "vsoo,txdwd"
            },
            {
                "name": "code",
                "datatype": "S",
                "value": "NEW_TELA_INDEX_SC_CODE_GOES_HERE"
            },
            {
                "name": "SC_ACTION",
                "datatype": "U",
                "value": 0
            },
            {
                "name": "SC_ID",
                "datatype": "H",
                "value": "your-index-scid"
            }
        ]
    }
}'

Version Control System

Built-in Commit Tracking

TELA-INDEX-1 automatically tracks all updates:

// Initialization (commit 0)
STORE("commit", 0)          // Version counter
STORE(0, HEX(TXID()))      // Initial TXID
STORE("hash", HEX(TXID())) // Current hash
 
// First update (commit 1)
STORE("commit", 1)
STORE(1, HEX(TXID()))      // Update TXID
STORE("hash", HEX(TXID())) // Updated hash
 
// Second update (commit 2)
STORE("commit", 2)
STORE(2, HEX(TXID()))
STORE("hash", HEX(TXID()))

Accessing Version History

# View all versions
» search scid vars your-index-scid
 
# Output shows:
# commit: 3           ← 3 updates made
# 0: abc123...        ← Initial deployment
# 1: def456...        ← First update
# 2: ghi789...        ← Second update
# 3: jkl012...        ← Third update (latest)
# hash: jkl012...     ← Current version

Clone Specific Version

# Clone latest version
» clone your-index-scid
 
# Clone specific commit
» clone your-index-scid@def456...  # First update
» clone your-index-scid@abc123...  # Original version

Serve Version Control

# Serve latest (default)
» updates true
» serve your-index-scid
 
# Serve original only
» updates false
» serve your-index-scid  # Always serves commit 0

DOC References

DOC1 (Entrypoint)

Special Requirement: DOC1 must be a valid TELA-DOC-1 SCID

40 STORE("DOC1", "valid-doc-scid-here")

Purpose:

Primary file loaded when INDEX is accessed
Usually index.html for web apps
Must exist and be valid for INDEX to work

Validation:

Cannot be empty
Must be 64-character hex SCID
Must reference valid TELA-DOC-1 contract

Additional DOCs (DOC2, DOC3, etc.)

Format:

41 STORE("DOC2", "second-doc-scid")
42 STORE("DOC3", "third-doc-scid")
43 STORE("DOC4", "fourth-doc-scid")
// Continue incrementing as needed

Rules:

Sequential numbering (DOC1, DOC2, DOC3...)
All DOC stores must have valid SCID values
Empty/invalid DOC stores will cause validation failure
Can include regular DOCs, libraries, and DocShards

Maximum DOCs

Practical Limits:

~90 DOCs   - Safe limit for updateable INDEX
~120 DOCs  - Maximum tested capacity
~unlimited - Theoretically, limited only by 11.64KB INDEX size

Each DOC SCID adds:

~64 bytes for the SCID itself
~10-20 bytes for STORE structure
~80 bytes total per DOC reference

Calculation:

11,640 bytes (max INDEX size)
- 1,000 bytes (base contract + headers)
- 10,640 bytes available for DOCs
÷ 80 bytes per DOC
≈ 133 DOCs theoretical maximum

Reality: ~120 DOCs due to contract overhead

dURL Conventions

The INDEX dURL identifies your application:

Standard Applications

myapp.tela              # Standard application
blog.tela               # Blog application
explorer.tela           # Block explorer
game.tela               # Game application

Special Suffixes

Suffix	Purpose	Example
`.lib`	Library INDEX	`mylib.tela.lib`
`.shards`	DocShard reconstruction	`largefile.tela.shards`

dURL Best Practices

✅ Descriptive and memorable
✅ Lowercase preferred
✅ Use hyphens for spaces (my-app.tela)
✅ Unique within your application ecosystem
❌ Don't use special characters
❌ Don't use spaces
❌ Don't exceed reasonable length (keep under 32 chars)

Rating Integration

INDEX contracts include built-in rating functionality:

Function Rate(r Uint64) Uint64
10 DIM addr as String
20 LET addr = ADDRESS_STRING(SIGNER())
30 STORE(addr, r)
40 RETURN 0
End Function

Rating via TELA-CLI

» rate your-index-scid
Enter rating (0-99) » 85
Rating is: 85  Very good (Benevolent)
Confirm rating (y/n) » y

Rating via Manual Transaction

GetGasEstimate:

curl -X POST http://127.0.0.1:20000/json_rpc \
  -H 'content-type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "DERO.GetGasEstimate",
    "params": {
        "transfers": [],
        "signer": "deto1qyre7td6x9r88y4cavdgpv6k7lvx6j39lfsx420hpvh3ydpcrtxrxqg8v8e3z",
        "sc_rpc": [
            {
                "name": "SC_ACTION",
                "datatype": "U",
                "value": 0
            },
            {
                "name": "SC_ID",
                "datatype": "H",
                "value": "your-index-scid"
            },
            {
                "name": "entrypoint",
                "datatype": "S",
                "value": "Rate"
            },
            {
                "name": "r",
                "datatype": "U",
                "value": 85
            }
        ]
    }
}'

Execute Transaction:

curl -X POST http://127.0.0.1:30002/json_rpc \
    -H 'content-type: application/json' \
    -d '{
    "jsonrpc": "2.0",
    "id": "0",
    "method": "Transfer",
    "params": {
        "ringsize": 2,
        "fees": 90,
        "sc_rpc": [
            {
                "name": "entrypoint",
                "datatype": "S",
                "value": "Rate"
            },
            {
                "name": "r",
                "datatype": "U",
                "value": 85
            },
            {
                "name": "SC_ACTION",
                "datatype": "U",
                "value": 0
            },
            {
                "name": "SC_ID",
                "datatype": "H",
                "value": "your-index-scid"
            }
        ]
    }
}'

Complete Example

Minimal INDEX (1 DOC)

Function InitializePrivate() Uint64
10 IF EXISTS("nameHdr") THEN GOTO 100
30 STORE("var_header_name", "Simple App")
31 STORE("var_header_description", "A minimal TELA application")
32 STORE("var_header_icon", "")
33 STORE("dURL", "simple.tela")
34 STORE("mods", "")
40 STORE("DOC1", "abc123def456...")  // Only index.html
90 STORE("commit", 0)
91 STORE(0, HEX(TXID()))
92 STORE("hash", HEX(TXID()))
100 RETURN 0
End Function

Multi-File INDEX (5 DOCs)

Function InitializePrivate() Uint64
10 IF EXISTS("nameHdr") THEN GOTO 100
30 STORE("var_header_name", "Complete App")
31 STORE("var_header_description", "Full-featured application")
32 STORE("var_header_icon", "https://cdn.example.com/icon.png")
33 STORE("dURL", "complete-app.tela")
34 STORE("mods", "")
40 STORE("DOC1", "111...")  // index.html (entrypoint)
41 STORE("DOC2", "222...")  // style.css
42 STORE("DOC3", "333...")  // app.js
43 STORE("DOC4", "444...")  // utils.js
44 STORE("DOC5", "555...")  // assets/logo.png
90 STORE("commit", 0)
91 STORE(0, HEX(TXID()))
92 STORE("hash", HEX(TXID()))
100 RETURN 0
End Function

INDEX with MODs

Function InitializePrivate() Uint64
10 IF EXISTS("nameHdr") THEN GOTO 100
30 STORE("var_header_name", "Enhanced App")
31 STORE("var_header_description", "App with variable storage and DERO deposits")
32 STORE("var_header_icon", "https://example.com/icon.png")
33 STORE("dURL", "enhanced.tela")
34 STORE("mods", "vsoo,txdwd,txto")  // MODs enabled!
40 STORE("DOC1", "abc...")
41 STORE("DOC2", "def...")
90 STORE("commit", 0)
91 STORE(0, HEX(TXID()))
92 STORE("hash", HEX(TXID()))
100 RETURN 0
End Function
 
// MOD functions are automatically injected here
// Example: SetVar, DeleteVar, DepositDero, WithdrawDero, TransferOwnership

Best Practices

Deployment Strategy

1. Plan Your Structure:

INDEX (myapp.tela)
├── DOC1: index.html (entrypoint) ← Always first
├── DOC2: style.css
├── DOC3: app.js
├── DOC4: utils.tela.lib (shared library)
└── DOC5: assets/logo.png

2. Deploy DOCs First:

» install-doc index.html  # → SCID: aaa...
» install-doc style.css   # → SCID: bbb...
» install-doc app.js      # → SCID: ccc...
# Note all SCIDs!

3. Create INDEX Last:

» install-index
# Reference all DOC SCIDs in order
# DOC1 must be your entrypoint

Update Strategy

When to Update:

✅ Adding new files (new DOC)
✅ Replacing old files (point to new DOC SCID)
✅ Removing unused files (reduce DOC count)
✅ Adding/removing MODs
✅ Updating metadata

When to Deploy New INDEX:

✅ Complete redesign
✅ Forking/cloning app
✅ Creating alternative version

Ringsize Decisions

Ringsize 2 (Updateable):

Enter INDEX install ringsize » 2

✅ Can update later
✅ Owner address is public
✅ Flexible development

Ringsize > 2 (Immutable):

Enter INDEX install ringsize » 16

✅ Maximum privacy/anonymity
✅ Cannot be censored by owner
❌ Cannot be updated (permanent!)

Error Handling

Common Errors

Error: "Invalid DOC1 SCID"

Solution: DOC1 must be a valid TELA-DOC-1 contract
Verify SCID with: » search scid [doc1-scid]

Error: "INDEX size exceeds maximum"

Solution: INDEX is > 11.64KB
1. Reduce number of DOCs
2. Use libraries to consolidate
3. Use DocShards instead of embedding all DOCs

Error: "Cannot update INDEX"

Reasons:
1. Not the contract owner
2. Contract deployed with ringsize > 2 (immutable)
3. Wrong SCID (verify with » search scid)

Error: "MOD validation failed"

Solution:
1. Check MOD tags are valid (» mods)
2. Verify MOD combination allowed (» mod-info [tag])
3. Ensure no conflicting MODs (Single MOD class rule)

Advanced Features

Dynamic Metadata (with MODs)

Update metadata without UpdateCode:

# Requires Variable Store MOD (vsoo, vspubow, etc.)
 
# Update app name
» set-var your-index-scid
Enter key » var_header_name
Enter value » My App v3.0 (Updated!)
 
# Update description
» set-var your-index-scid
Enter key » var_header_description
Enter value » Now with new features!
 
# Add category metadata
» set-var your-index-scid
Enter key » var_meta_category
Enter value » Productivity

Benefits:

❌ Doesn't create new commit version
✅ Instant metadata updates
✅ Lower transaction fees
✅ Useful for status messages

Library Bundles

Create an INDEX that bundles multiple libraries:

// Library bundle INDEX
33 STORE("dURL", "ui-framework.tela.lib")
40 STORE("DOC1", "lib-buttons.scid")     // Button components
41 STORE("DOC2", "lib-forms.scid")       // Form components
42 STORE("DOC3", "lib-modals.scid")      // Modal components
43 STORE("DOC4", "lib-tables.scid")      // Table components

Usage: Other apps can reference this one INDEX SCID to get all libraries

DocShard INDEX

Create an INDEX that reconstructs large files:

// DocShard INDEX (requires .shards in dURL)
33 STORE("dURL", "bigfile.tela.shards")
40 STORE("DOC1", "index.html.scid")       // Regular entrypoint
41 STORE("DOC2", "shard-1.scid")          // Large file shard 1
42 STORE("DOC3", "shard-2.scid")          // Large file shard 2
43 STORE("DOC4", "shard-3.scid")          // Large file shard 3

Auto-reconstruction: TELA detects .shards tag and rebuilds the file

Complete Contract Example

Full TELA-INDEX-1 with MODs and multiple DOCs:

Function InitializePrivate() Uint64
10 IF EXISTS("nameHdr") THEN GOTO 100
30 STORE("var_header_name", "DERO Block Explorer")
31 STORE("var_header_description", "Real-time blockchain explorer for DERO network")
32 STORE("var_header_icon", "https://cdn.example.com/explorer-icon.png")
33 STORE("dURL", "dero-explorer.tela")
34 STORE("mods", "vsoo,txdwd")
40 STORE("DOC1", "abc123...")  // index.html
41 STORE("DOC2", "def456...")  // style.css
42 STORE("DOC3", "ghi789...")  // app.js
43 STORE("DOC4", "jkl012...")  // blocks.js
44 STORE("DOC5", "mno345...")  // transactions.js
45 STORE("DOC6", "pqr678...")  // utils.tela.lib (external library)
90 STORE("commit", 0)
91 STORE(0, HEX(TXID()))
92 STORE("hash", HEX(TXID()))
100 RETURN 0
End Function
 
Function UpdateCode(mods String, code String) Uint64
10 DIM codeHash, newCode as String
20 LET codeHash = HEX(TXID())
30 IF LOAD("owner") == SIGNER() THEN GOTO 50
40 RETURN 1
50 STORE("commit", LOAD("commit")+1)
60 STORE(LOAD("commit"), codeHash)
70 STORE("hash", codeHash)
80 LET newCode = code
90 UPDATE_SC_CODE(newCode)
100 RETURN 0
End Function
 
Function Rate(r Uint64) Uint64
10 DIM addr as String
20 LET addr = ADDRESS_STRING(SIGNER())
30 STORE(addr, r)
40 RETURN 0
End Function
 
// TELA-MOD-1 functions injected here (SetVar, DeleteVar, etc.)