Skip to content

TEMPLATE_MARKETPLACE.md

Latest commit

 

History

History
328 lines (259 loc) · 7.96 KB

TEMPLATE_MARKETPLACE.md

File metadata and controls

328 lines (259 loc) · 7.96 KB

Template Marketplace Feature

Overview

The Template Marketplace feature enables community-contributed Soroban smart contract templates with versioning, discovery, and easy scaffolding. This allows developers to quickly bootstrap projects using battle-tested templates from the community.

Features

1. Template Discovery

Search and browse available templates by name, description, or tags:

# Search for DeFi templates
starforge template search defi

# Search with tag filtering
starforge new contract --search defi --tags dex,amm

# List all available templates
starforge template list

# View detailed information about a template
starforge template show uniswap-v2

2. Template Usage

Scaffold new projects using marketplace templates:

# Use a marketplace template
starforge new contract my-dex --template uniswap-v2 --from marketplace

# Search and use in one workflow
starforge new contract --search lending
# Then use the found template
starforge new contract my-lending --template lending-pool --from marketplace

3. Template Publishing

Share your templates with the community:

# Publish a template
starforge template publish ./my-template \
  --name my-awesome-template \
  --description "An awesome Soroban contract" \
  --author "Your Name" \
  --tags "defi,custom" \
  --version "1.0.0"

# Interactive publishing (prompts for missing info)
starforge template publish ./my-template

4. Template Management

Manage your local template registry:

# Initialize registry with example templates
starforge template init

# Remove a template
starforge template remove my-template

Template Structure

Required Files

Every template must contain:

  • Cargo.toml - Rust package manifest
  • src/ directory - Source code
  • src/lib.rs - Main contract file

Optional Files

  • README.md - Documentation
  • .cargo/config.toml - Cargo configuration
  • tests/ - Test files

Template Placeholders

Templates support automatic variable substitution:

Placeholder Example Input Example Output
{{PROJECT_NAME}} my-project my-project
{{PROJECT_NAME_SNAKE}} my-project my_project
{{PROJECT_NAME_PASCAL}} my-project MyProject

Example usage in Cargo.toml:

[package]
name = "{{PROJECT_NAME}}"
version = "0.1.0"

Example usage in src/lib.rs:

#[contract]
pub struct {{PROJECT_NAME_PASCAL}};

Template Sources

Templates can be sourced from three locations:

1. Git Repository

{
  "source": {
    "type": "git",
    "url": "https://github.com/user/repo",
    "branch": "main"
  }
}

2. Local Path

{
  "source": {
    "type": "local",
    "path": "/path/to/template"
  }
}

3. Built-in

{
  "source": {
    "type": "builtin",
    "id": "hello-world"
  }
}

Registry Format

The template registry is stored in ~/.starforge/templates/registry.json:

{
  "version": "1",
  "templates": [
    {
      "name": "uniswap-v2",
      "version": "1.0.0",
      "description": "Uniswap V2 style AMM DEX",
      "author": "Stellar Community",
      "tags": ["defi", "dex", "amm"],
      "source": {
        "type": "git",
        "url": "https://github.com/stellar/soroban-examples",
        "branch": "main"
      },
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-01T00:00:00Z",
      "downloads": 42,
      "verified": true
    }
  ]
}

Template Verification

Templates can be marked as verified: true by maintainers. Verified templates:

  • Have been reviewed for security and quality
  • Follow Soroban best practices
  • Include proper documentation
  • Have working tests

Verified templates appear first in search results with a ✓ badge.

Example Workflow

For Template Users

  1. Discover templates:

    starforge template search defi

  2. View template details:

    starforge template show uniswap-v2

  3. Create project from template:

    starforge new contract my-dex --template uniswap-v2 --from marketplace

  4. Build and deploy:

    cd my-dex
stellar contract build
starforge deploy --wasm target/wasm32-unknown-unknown/release/my_dex.wasm

For Template Authors

  1. Create your template:

    # Create a new contract as usual
starforge new contract my-template
cd my-template

# Add your custom logic
# Replace hardcoded names with placeholders

  2. Add placeholders:

    // In src/lib.rs
#[contract]
pub struct {{PROJECT_NAME_PASCAL}};

  3. Test the template:

    cargo test
stellar contract build

  4. Publish to marketplace:

    cd ..
starforge template publish ./my-template \
  --name my-awesome-template \
  --description "Does something awesome" \
  --author "Your Name" \
  --tags "defi,awesome" \
  --version "1.0.0"

  5. Share with others:

    # Others can now use it
starforge new contract test-project --template my-awesome-template --from marketplace

Built-in Example Templates

The marketplace includes several example templates:

  1. uniswap-v2 - AMM DEX implementation
  2. lending-pool - Lending and borrowing protocol
  3. governance - DAO governance with voting
  4. multisig-wallet - Multi-signature wallet

Initialize these with:

starforge template init

Implementation Details

File Structure

src/
├── commands/
│   ├── new.rs          # Extended with marketplace support
│   └── template.rs     # New template management commands
├── utils/
│   └── templates.rs    # Template registry and operations
templates/
├── registry.json       # Default template registry
├── README.md          # Template documentation
└── examples/
    └── simple-counter/ # Example template

Key Functions

Template Discovery:

  • search_templates(query, tags) - Search with filtering
  • get_template(name) - Get specific template
  • load_registry() - Load template registry

Template Operations:

  • fetch_template(entry, dest) - Download/copy template
  • validate_template_structure(path) - Validate template
  • publish_template(...) - Publish new template

Registry Management:

  • add_template(entry) - Add to registry
  • remove_template(name) - Remove from registry
  • save_registry(registry) - Persist changes

Future Enhancements

Potential improvements for future versions:

  1. Remote Registry - Central registry server for global template sharing
  2. Template Versioning - Support multiple versions of the same template
  3. Template Updates - Update existing templates to newer versions
  4. Template Dependencies - Templates that depend on other templates
  5. Template Categories - Organize templates into categories
  6. Template Ratings - Community ratings and reviews
  7. Template Analytics - Usage statistics and popularity metrics
  8. Template CI/CD - Automated testing and verification
  9. Template Marketplace UI - Web interface for browsing templates

Security Considerations

When using templates from the marketplace:

  1. Review Code - Always review template code before using
  2. Verify Source - Check the template source (Git URL, author)
  3. Use Verified - Prefer verified templates when available
  4. Test Thoroughly - Test templates in a safe environment first
  5. Update Dependencies - Keep template dependencies up to date

Contributing

To contribute templates to the official registry:

  1. Create a high-quality template following best practices
  2. Test thoroughly with multiple project names
  3. Add comprehensive documentation
  4. Submit a PR adding your template to templates/registry.json
  5. Include examples and usage instructions

Support

For issues or questions: