Template Contribution Guidelines

Thank you for contributing a smart contract template to the StarForge library! This document covers every step from writing your template to getting it accepted.

Quick-start checklist

Before opening a pull request, confirm each item:

Template structure

Every template lives under templates/examples/<template-name>/ and follows this layout:

templates/examples/<template-name>/
├── Cargo.toml          # crate manifest — uses {{project_name_snake}}
├── README.md           # user-facing documentation
└── src/
    └── lib.rs          # contract source

Cargo.toml requirements

[package]
name = "{{project_name_snake}}"
version = "0.1.0"
edition = "2021"

[lib]
crate-type = ["cdylib"]

[dependencies]
soroban-sdk = { version = "22.0.0", features = ["alloc"] }

[dev-dependencies]
soroban-sdk = { version = "22.0.0", features = ["testutils"] }

Use {{project_name_snake}} as the crate name — StarForge replaces this with the user's project name when scaffolding.

Contract source requirements

Must start with #![no_std]
Must use {{PROJECT_NAME_PASCAL}} as the contract struct name (double-brace placeholder)
Must include a module-level doc comment (//! …) explaining the contract
Must include a #[cfg(test)] mod test { … } block with at least two meaningful tests
Must compile without warnings

#![no_std]
//! Brief description of the contract.
use soroban_sdk::{contract, contractimpl, Env};

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

#[contractimpl]
impl {{PROJECT_NAME_PASCAL}} {
    // ...
}

#[cfg(test)]
mod test {
    use super::*;

    #[test]
    fn test_happy_path() { /* ... */ }

    #[test]
    #[should_panic(expected = "…")]
    fn test_error_case() { /* ... */ }
}

Registry entry

Every template must have a corresponding entry in templates/registry.json. Below is the minimum required shape:

{
  "name": "my-template",
  "version": "1.0.0",
  "description": "One-line description of what the contract does",
  "author": "Your Name",
  "tags": ["defi", "my-category"],
  "source": { "type": "builtin", "id": "my-template" },
  "created_at": "2025-01-01T00:00:00Z",
  "updated_at": "2025-01-01T00:00:00Z",
  "verified": false,
  "documented": true,
  "maintenance": "active",
  "license": "MIT",
  "security_review": {
    "status": "pending",
    "audited_at": null,
    "auditor": null,
    "findings": null,
    "score": null
  },
  "changelog": [
    { "version": "1.0.0", "date": "2025-01-01", "notes": "Initial release" }
  ]
}

Field reference

Field	Required	Description
`name`	✓	Unique kebab-case identifier
`version`	✓	Semver string (`major.minor.patch`)
`description`	✓	One-line summary (≤ 120 chars)
`author`	✓	Author name or GitHub handle
`tags`	✓	At least one tag from the tag taxonomy
`source`	✓	`builtin`, `git`, or `local` source descriptor
`license`	recommended	SPDX identifier (`MIT`, `Apache-2.0`, …)
`security_review`	recommended	Audit status — `pending` is fine initially
`changelog`	recommended	At least one entry
`maintenance`	recommended	`active`, `maintained`, `deprecated`, or `unknown`

security_review.findings is a number (the count of findings) or null — not a quoted string.

Validating your entry

templates/registry.schema.json is the authoritative shape of a registry entry, and StarForge validates against it before loading any registry. Check your entry before opening a pull request:

# the whole registry, including your new entry
starforge template validate templates/registry.json

# or just your entry, saved to its own file
starforge template validate ./my-template.json

Problems are reported field by field, so you can fix them directly:

templates[12].version: 'v1.0' is not valid semver (expected major.minor.patch, e.g. "1.2.0")
templates[12].changelog[0].date: '01/06/2025' is not a date in YYYY-MM-DD form
templates[12].source.id: required field is missing

Field names the schema does not know are reported as warnings rather than errors, so a typo like descripton shows up without breaking older CLIs that read a newer registry. See templates/README.md for the full list of checks.

Tag taxonomy

Use at least one of these standard tags so search works reliably:

Tag	Used for
`token`	Fungible token contracts
`nft`	Non-fungible token contracts
`defi`	DeFi primitives (AMM, lending, staking, …)
`dao`	Governance / DAO contracts
`governance`	Voting and proposal contracts
`multisig`	Multi-signature wallets and vaults
`security`	Auth, access-control, and audit-focused contracts
`payments`	Payment channels, escrow, and invoicing
`staking`	Yield / staking contracts
`standard`	SEP-conformant contracts

Security review process

The StarForge Security Team reviews every new template before setting verified: true. Until review is complete, the template is published with "status": "pending".

What gets reviewed

Authorization checks — every mutating function calls require_auth() on the right principal; no function can be called by an arbitrary address.
Re-entrancy — state is updated before external token transfers.
Integer arithmetic — no unchecked arithmetic that could overflow or wrap.
Initialization guards — contracts cannot be re-initialized.
Storage hygiene — correct use of instance, persistent, and temporary storage lifetimes.
Panic messages — descriptive error strings, no empty panics.

Review SLA

Priority	Target turnaround
Security fix	48 hours
New template	7 days
Version bump	5 days

Requesting an expedited review

Open a GitHub issue with the label security-review-request and link your PR. The Security Team triages these daily.

Version bumping

When updating an existing template:

Increment the version field in the registry.json entry following semver:
- Patch (x.y.Z) — bug fixes, doc improvements, no API changes.
- Minor (x.Y.0) — new optional functions, backward-compatible changes.
- Major (X.0.0) — breaking changes to the public API.
Add a new entry at the top of the changelog array.
Update updated_at to the current date.
Reset security_review.status to "pending" if the change affects contract logic.

Testing your template

Run the template's own tests from the StarForge CLI before submitting:

# Run tests via cargo directly
cargo test --manifest-path templates/examples/my-template/Cargo.toml

# Or via the CLI (once registered)
starforge template test my-template

All tests must pass with zero warnings.

Generating documentation

After adding your registry entry you can preview the generated Markdown docs:

starforge template docs my-template
# write to a file
starforge template docs my-template --output docs/templates/my-template.md

Pull request process

Fork the repo and create a branch: git checkout -b feat/template-my-template
Add your template files and registry entry.
Run cargo test from the repo root to verify nothing is broken.
Open a PR against main with the title feat(templates): add my-template.
Fill in the PR description template, including the checklist above.
The Security Team will review and either approve or request changes within 7 days.

We appreciate every contribution — thank you for making the Stellar ecosystem stronger!

FilesExpand file tree

TEMPLATE_CONTRIBUTING.md

Latest commit

History