TELA-DOC-1 Specification

Complete technical specification for TELA-DOC-1 smart contracts - the standard for storing code files on the DERO blockchain.

📄

What is TELA-DOC-1? A smart contract standard that stores individual files (HTML, CSS, JavaScript, etc.) on the DERO blockchain with cryptographic verification and immutability.

Overview

TELA-DOC-1 contracts contain the essential code required by TELA applications. Each DOC contract stores a single file with metadata, cryptographic signatures, and content.

Key Characteristics

Property	Value
Mutability	🔒 Immutable (cannot be changed after deployment)
Max Size	20KB total contract size
Code Limit	18KB code content
Purpose	Store individual application files
Versioning	New versions = new SCID (immutable history)
Security	Cryptographically signed by author

Supported File Types (docTypes)

TELA-DOC-1 supports these document types:

docType	Extension	Purpose	Examples
TELA-HTML-1	`.html`	Page structure	index.html, about.html
TELA-CSS-1	`.css`	Styling	style.css, theme.css
TELA-JS-1	`.js`	Application logic	app.js, utils.js
TELA-JSON-1	`.json`	Data & configuration	config.json, data.json
TELA-MD-1	`.md`	Documentation	README.md, docs.md
TELA-GO-1	`.go`	Go source code	main.go, utils.go
TELA-STATIC-1	Other	Images, fonts, assets	logo.png, font.woff

Accepted Languages

The civilware/tela Go package validates these languages:

// Accepted languages (from source code)
HTML, JSON, JavaScript, CSS, Markdown, Static

Static Type: Encompasses any desired files not listed as accepted languages (images, fonts, assets, build files, etc.)

Size Constraints

⚠️

Critical Limits - NEVER Exceed These

These are absolute blockchain limits enforced by the DERO network.

Hard Limits (from parse.go)

Limit	Size	Constant Name
DOC Code Content	18.00 KB	MAX_DOC_CODE_SIZE
DOC Total Contract	20.00 KB	MAX_DOC_INSTALL_SIZE
Recommended Maximum	18.00 KB	For reliable deployment

Why 18KB for code?

Contract headers and structure use ~2KB
18KB code + 2KB structure = 20KB total
Staying at 18KB ensures room for headers

Size Violations

Error Messages (from source):

"docCode size is to large, max 18.00KB (actual: 19.25KB)"
"DOC SC size is to large, max 20.00KB (actual: 21.50KB)"

Solutions:

Minify code - Remove whitespace and comments
Use compression - Gzip encoding (automatic with TELA-CLI)
Split into multiple DOCs - Use DocShards for files >18KB

Smart Contract Structure

TELA-DOC-1 Template

The smart contract consists of:

Function InitializePrivate() Uint64
// Input fields (lines 30-37)
30 STORE("var_header_name", "index.html")
31 STORE("var_header_description", "A HTML index")
32 STORE("var_header_icon", "https://example.com/icon.png")
33 STORE("dURL", "app.tela")
34 STORE("docType", "TELA-HTML-1")
35 STORE("subDir", "")
36 STORE("fileCheckC", "1c37f9e61f15a9526ba680dce0baa567e642ca2cd0ddea71649dab415dad8cb2")
37 STORE("fileCheckS", "7e642ca2cd0ddea71649dab415dad8cb21c37f9e61f15a9526ba680dce0baa56")
// Input fields end
100 RETURN 0
End Function
 
/* 
[ACTUAL FILE CONTENT GOES HERE]
<!DOCTYPE html>
<html>
<head>
    <title>My TELA App</title>
</head>
<body>
    <h1>Hello TELA!</h1>
</body>
</html>
*/

Contract Variables (STORE Parameters)

Variable	Type	Required	Description
`var_header_name`	String	Yes	File name (e.g., "index.html")
`var_header_description`	String	No	Description of the file
`var_header_icon`	String	No	Icon URL or SCID (100x100px recommended)
`dURL`	String	Yes	Decentralized URL identifier
`docType`	String	Yes	File type (TELA-HTML-1, TELA-JS-1, etc.)
`subDir`	String	No	Subdirectory path (e.g., "/assets/", "/js/")
`fileCheckC`	String	Yes	Signature C value (cryptographic proof)
`fileCheckS`	String	Yes	Signature S value (cryptographic proof)

dURL (Decentralized URL)

The dURL is a unique identifier for the DOC contract.

Format Guidelines

Standard DOC:

myapp.tela          # Regular application file
homepage.tela       # Another file
utils.tela          # Utility file

Library DOC:

mylib.tela.lib      # Library identifier
utils.tela.lib      # Shared utility library

DocShard DOC:

largefile.tela.shard    # Individual shard
largefile.tela.shards   # INDEX for shards

dURL Best Practices

✅ Use lowercase
✅ Use descriptive names
✅ Include file purpose
✅ Use .lib suffix for libraries
✅ Use .shard/.shards for DocShards
❌ Don't use spaces or special characters
❌ Don't duplicate existing dURLs in your INDEX

Subdirectories (subDir)

Organize files in directory structure:

subDir Value	Result Path	Use Case
`""`	`/index.html`	Root directory
`"assets/"`	`/assets/logo.png`	Asset files
`"js/"`	`/js/app.js`	JavaScript files
`"css/"`	`/css/style.css`	Stylesheets
`"lib/"`	`/lib/utils.js`	Libraries
`"assets/icons/"`	`/assets/icons/logo.svg`	Nested directories

Rules:

Always use forward slashes /
End with / for directories
Can be nested: sub1/sub2/sub3/

Cryptographic Signatures

TELA-DOC contracts include DERO signatures for file verification.

Signature Components

Component	Description
`fileCheckC`	C value from DERO signature (hex string)
`fileCheckS`	S value from DERO signature (hex string)

How Signatures Work

// 1. Author signs the file content with their wallet
signature := wallet.SignData(fileContent)
 
// 2. Parse signature to get C and S values  
c, s := ParseSignature(signature)
 
// 3. Store in contract
STORE("fileCheckC", c)
STORE("fileCheckS", s)
 
// 4. Verification (when serving)
// Clients verify signature matches author's public key
// Ensures code hasn't been tampered with

Purpose:

Authenticity - Proves author created the file
Integrity - Detects any tampering
Trust - Users can verify code origin

Deployment Preparation

Guidelines

Before deploying a TELA-DOC-1:

Size Check:

# Verify file is under 18KB
ls -lh myfile.html
wc -c myfile.html

Character Encoding:
- Use ASCII characters when possible
- Non-ASCII characters should be encoded
- Compression handles encoding automatically
Comments:
- /* */ multiline comments may cause issues
- Use // single-line comments for JavaScript
- Or use compression (recommended)

Test Locally:

» serve local ./project
# Verify functionality before deploying

File Content Preparation

HTML Example:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>My TELA App</title>
    <link rel="stylesheet" href="style.css">
</head>
<body>
    <h1>Hello TELA!</h1>
    <script src="app.js"></script>
</body>
</html>

JavaScript Example:

// TELA application code
({
    name: 'my-app',
    version: '1.0.0',
    
    init: function() {
        console.log('App initialized');
    }
});

CSS Example:

body {
    font-family: Arial, sans-serif;
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
    color: white;
}

Compression

TELA supports Gzip compression for DOC content.

When to Compress

File Size	Recommendation
< 10KB	Optional
10-15KB	Recommended
15-18KB	Strongly recommended
> 18KB	Required (or use DocShards)

Compression Format

Filename Convention:

original.html       → original.html.gz
app.js             → app.js.gz
data.json          → data.json.gz

TELA-CLI Handling:

Automatically compresses when beneficial
Adds .gz extension to nameHdr
Decompresses automatically when serving

Manual Compression:

# Compress file
gzip -c original.html > original.html.gz
 
# Deploy compressed version
» install-doc original.html.gz

TELA Libraries

TELA libraries are reusable code modules designed for universal use across applications.

Library Identification

dURL Convention:

utils.tela.lib          # Library identifier
components.tela.lib     # UI components library
helpers.tela.lib        # Helper functions

Benefits:

✅ Code reuse across applications
✅ Reduced blockchain bloat
✅ Community-tested solutions
✅ Faster development
✅ Consistent patterns

Library Usage

Include in your INDEX:

INDEX {
    DOC1: "your-index-html-scid",
    DOC2: "your-style-css-scid",
    DOC3: "library-utils-scid",      // External library
    DOC4: "library-components-scid"  // Another library
}

Access in your code:

<!-- Library is automatically included -->
<script src="utils.tela.lib.js"></script>

Library Creation

Single-file library:

» install-doc utils.js
Enter DOC dURL » utils.tela.lib  # .lib suffix

Multi-file library:

# Deploy all library files
» install-doc lib-core.js      # dURL: mylib.tela.lib
» install-doc lib-helpers.js   # dURL: mylib.tela.lib
» install-doc lib-ui.js        # dURL: mylib.tela.lib
 
# Create library INDEX
» install-index
Enter INDEX dURL » mylib.tela.lib  # .lib suffix

DocShards

DocShards enable files larger than 18KB to be deployed across multiple DOC contracts and automatically reconstructed.

Shard Size

Constant	Value	Purpose
SHARD_SIZE	17,500 bytes	Exact size per shard

Why 17,500?

Leaves room for contract structure
Ensures reliable deployment
Prevents size limit violations

DocShard Creation

Automatic (TELA-CLI):

» file-shard largefile.js
 
# Creates:
# - largefile-1.js (17,500 bytes)
# - largefile-2.js (17,500 bytes)
# - largefile-3.js (remaining bytes)

Deploy Shards:

» install-doc largefile-1.js  # dURL: largefile.tela.shard
» install-doc largefile-2.js  # dURL: largefile.tela.shard
» install-doc largefile-3.js  # dURL: largefile.tela.shard
 
# Create INDEX with .shards tag
» install-index
Enter INDEX dURL » largefile.tela.shards
How many total documents? » 3
Enter DOC1 SCID » [shard-1-scid]
Enter DOC2 SCID » [shard-2-scid]
Enter DOC3 SCID » [shard-3-scid]

DocShard Reconstruction

When cloned or served, shards are automatically reconstructed:

Clone or Serve INDEX with .shards tag
  ↓
TELA detects .shards in dURL
  ↓
Fetches all shard DOCs
  ↓
Reconstructs original file
  ↓
Saves to: dURL/nameHdr

⚠️

Important: DocShards cannot be the entrypoint (DOC1) of an INDEX. Use regular DOCs for entrypoint, DocShards for additional files.

Smart Contract Functions

InitializePrivate()

Purpose: Called once when contract is deployed

Actions:

Stores all metadata (name, description, icon, dURL, etc.)
Stores file content in multiline comment
Stores cryptographic signature
Initializes contract state

Cannot be called again - Contract is immutable after deployment

Rate(r Uint64)

Purpose: Rate the DOC contract quality

Parameters:

r - 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

Deployment Procedures

Using TELA-CLI (Recommended)

» install-doc ./myfile.html
Confirm password » ****
Enter DOC file path » ./myfile.html
Enter DOC description » My HTML file
Enter DOC icon » https://example.com/icon.png
Enter DOC dURL » myfile.tela
Enter DOC subDir » 
Enter DOC install ringsize » 2
Confirm DOC install (y/n) » y
 
# Output: DOC install TXID: abc123...

Manual Deployment (Advanced)

Step 1: Prepare Contract

Edit TELA-DOC-1.bas template:

30 STORE("var_header_name", "index.html")
31 STORE("var_header_description", "My app homepage")
32 STORE("var_header_icon", "https://example.com/icon.png")
33 STORE("dURL", "myapp-home.tela")
34 STORE("docType", "TELA-HTML-1")
35 STORE("subDir", "")
36 STORE("fileCheckC", "[C-value-from-signature]")
37 STORE("fileCheckS", "[S-value-from-signature]")
 
/*
<!DOCTYPE html>
<html>
<head><title>My App</title></head>
<body><h1>Hello TELA!</h1></body>
</html>
*/

Step 2: Deploy Contract

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

Step 3: Note SCID

The response includes the new contract SCID - save this for use in INDEX contracts.

Best Practices

File Organization

Single-purpose files:

✅ index.html     - Homepage only
✅ about.html     - About page only
✅ app.js         - Core app logic
✅ utils.js       - Utility functions

Avoid kitchen-sink files:

❌ everything.html  - HTML + inline CSS + inline JS (bloated)

Naming Conventions

File names (var_header_name):

✅ index.html
✅ app.js
✅ style-v2.css
❌ MyFile.HTML (prefer lowercase)
❌ file with spaces.html (no spaces)

dURLs:

✅ myapp-homepage.tela
✅ app-utils.tela.lib
✅ largefile.tela.shard
❌ MyApp Homepage.tela (no spaces/caps)

Size Optimization

Remove unnecessary content:

// ❌ Remove console logs in production
console.log('Debug info...');
 
// ❌ Remove comments
/* This is a long comment explaining... */
 
// ❌ Remove unused functions
function neverUsed() { }

Minify before deployment:

# CSS
npx cssnano input.css output.min.css
 
# JavaScript  
npx terser input.js -o output.min.js -c -m
 
# HTML
npx html-minifier input.html -o output.min.html

Use compression:
- TELA-CLI handles this automatically
- Can reduce size by 60-70% for text files

Immutability Implications

🔒

Critical Understanding: Once a TELA-DOC-1 is deployed, it CANNOT be modified. Plan accordingly!

What Immutability Means

Cannot Change:

❌ File content
❌ Metadata (name, description, icon)
❌ Signature
❌ Any STORE values

Can Do:

✅ Deploy new version (new SCID)
✅ Update INDEX to point to new version
✅ Rate the content
✅ Keep old version accessible

Version Management Strategy

Version 1.0 → DOC Contract (SCID: abc...)
Version 1.1 → DOC Contract (SCID: def...)
Version 2.0 → DOC Contract (SCID: ghi...)
             ↓
        INDEX Contract
        Can update to point to any version
        All versions remain on blockchain

Example:

# Deploy version 1
» install-doc v1/index.html  # SCID: abc123...
 
# Later: Deploy version 2
» install-doc v2/index.html  # SCID: def456...
 
# Update INDEX to use v2
» update-index your-index-scid
# Change DOC1 from abc123... to def456...
 
# Users now see v2, but v1 still exists on blockchain

Error Handling

Common Deployment Errors

Error: "File too large"

Solution:
1. Check actual size: wc -c myfile.html
2. Minify the file
3. Use compression
4. Split into DocShards if >18KB even after compression

Error: "Invalid docType"

Solution: Ensure filename has valid extension
Supported: .html, .css, .js, .json, .md, .go

Error: "Invalid signature"

Solution: Signature must match file content exactly
Use TELA-CLI for automatic signature generation

Error: "Contract installation failed"

Solution:
1. Verify wallet has sufficient DERO
2. Check network connection
3. Ensure daemon is synced
4. Try higher ringsize for privacy

Advanced Topics

Character Encoding

ASCII vs Non-ASCII:

// ✅ ASCII characters (safe)
var text = "Hello TELA!";
 
// ⚠️ Non-ASCII (may need encoding)
var text = "Hello TELA! 🚀";  // Emoji
var text = "Bonjour TELA!";   // Accented chars
 
// ✅ Solution: Use compression
// TELA-CLI handles encoding automatically with compression

Multi-line Comments

Problematic:

/* 
This multi-line comment
might cause deployment issues
*/

Safe:

// Use single-line comments instead
// They don't cause parsing issues
// And work reliably

Best Solution: Use compression which handles all comment types

File References

Relative paths work:

<!-- DOC structure handles paths automatically -->
<link rel="stylesheet" href="style.css">
<script src="app.js"></script>
<img src="assets/logo.png">

How TELA resolves:

INDEX Contract
  ↓
DOC1: index.html (subDir: "")
DOC2: style.css (subDir: "")
DOC3: app.js (subDir: "")
DOC4: logo.png (subDir: "assets/")
  ↓
When served:
/index.html
/style.css
/app.js
/assets/logo.png

Contract Code Example

Complete example TELA-DOC-1 for an HTML file:

Function InitializePrivate() Uint64
10 IF EXISTS("nameHdr") THEN GOTO 100
30 STORE("var_header_name", "homepage.html")
31 STORE("var_header_description", "Application homepage with modern design")
32 STORE("var_header_icon", "https://mycdn.com/icon-100x100.png")
33 STORE("dURL", "myapp-home.tela")
34 STORE("docType", "TELA-HTML-1")
35 STORE("subDir", "")
36 STORE("fileCheckC", "a1b2c3d4e5f6...")
37 STORE("fileCheckS", "f6e5d4c3b2a1...")
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
 
/*
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>My TELA App</title>
    <style>
        body { font-family: Arial; padding: 20px; }
    </style>
</head>
<body>
    <h1>Welcome to My TELA Application</h1>
    <p>This app runs entirely on the DERO blockchain!</p>
</body>
</html>
*/