Templates

The AssemblyScript SDK includes starter contracts under:

apps/noos-contract-sdk-as/templates/

Use templates when you want a small, reviewable contract shape that already has source code, a manifest, example inputs, and package notes. They are starting points, not production approvals. After copying one, you still need to review the manifest, build the WASM, package it, sign it when required, and submit the right transactions for your network.

Commands

List templates:

npm run contracts:as-sdk:templates:list

Copy a template:

npm run contracts:as-sdk:templates:copy -- --template basic-storage --out my-basic-storage-contract

Test the complete template library:

npm run contracts:as-sdk:test:templates

The copy command refuses to overwrite an existing output directory. Pick a new directory or remove/rename the old one yourself after checking that it is safe.

Template Chooser

Template	Start here when	Main review focus
basic-storage	You need the smallest contract-state read/write example.	Storage key design, method authorization, event and return schemas.
bucket-metadata-reader	You need to read bucket metadata without requiring local ciphertext.	Bucket id, bucket:read_metadata, and metadata-only availability.
encrypted-record-metadata-writer	You need to write encrypted-record metadata or public indexes without plaintext.	Bucket write permission, deterministic payload hashes, and public index schema.
c2c-target	You need a method callable only by a known contract.	Target invoke.allow should name the caller contract principal.
c2c-caller	You need a manifest-declared contract-to-contract call.	Outbound calls entry, target id, target method, and nested-call failure behavior.
events-and-returns	You need a compact example of ABI input, structured returns, and events.	Event topics, output shape, and status/result conventions.
migration-enabled	You need a contract-defined migration entrypoint for upgrade jobs.	Migration id, source/target versions, batch size, fuel, and MigrationOutput.

What A Template Contains

Each template has the same basic layout:

assembly/index.ts
asconfig.json
package/manifest.json
package/README.md
package/examples/*.json

File	Purpose
assembly/index.ts	AssemblyScript source exported to WASM.
asconfig.json	AssemblyScript build configuration for the template.
package/manifest.json	Consensus-significant contract manifest. Review this carefully.
package/README.md	Short explanation of the template's intent.
package/examples/*.json	Example method arguments for tests, publishing, or manual calls.

The manifest is not documentation only. It defines method names, entrypoints, invocation policy, bucket requirements, C2C edges, ABI, events, migrations, and runtime expectations. If you change the code, update the manifest. If you change the manifest, rebuild and repackage before signing or publishing.

Template Details

basic-storage

Demonstrates isolated contract storage with put and get methods. The manifest restricts calls to organization org-noos and declares no bucket requirements.

Customize:

• package name and version;
• storage key format;
• invoke.allow;
• ABI input/output schemas;
• event topic storage.put.

Review that keys are bounded and namespaced. Avoid turning this into an unbounded map scan; contract storage helpers are intended for deterministic point reads and writes.

bucket-metadata-reader

Demonstrates bucketGetMetadata... host access. The manifest declares bucket-reports, metadata availability, and the bucket metadata read permission.

Customize:

• bucket id;
• method name and ABI;
• caller policy;
• event topic bucket.metadata.read.

This template does not require local encrypted payload availability because it reads metadata only. The deployed contract principal still needs the matching bucket access rule before calls are ready.

encrypted-record-metadata-writer

Demonstrates adding encrypted-record metadata and public indexes. Contracts do not receive plaintext, DEKs, private keys, or key envelopes.

Customize:

• bucket id and bucket permission declared in the manifest;
• record id and payload hash validation;
• public index fields;
• caller policy;
• event topic encrypted_record.metadata.written.

Keep payload hashes and public indexes deterministic. Review the target bucket's index schema so the contract writes metadata the bucket can accept.

c2c-target

Demonstrates a target method restricted to a specific caller contract principal. The template method ping allows principalType: "contract" with principalId: "contract-c2c-caller".

Customize:

• target contract id;
• allowed caller contract id;
• method name and ABI;
• event topic c2c.target.ping.

This authorizes the immediate caller contract. The original user is still tracked by the runtime, but the target method's invoke.allow check is against the direct caller contract.

c2c-caller

Demonstrates contractCallJson(...) and a manifest-declared outbound call. The manifest includes:

{
  "calls": [{ "contractId": "contract-c2c-target", "methods": ["ping"] }]
}

Customize:

• target contract id;
• allowed target methods;
• required buckets on the outbound edge, if the target needs them;
• caller method policy;
• event topic c2c.caller.result.

Nested calls fail deterministically when the target contract is missing, deactivated, not ready, not allowed by manifest policy, or fails during execution. Parent staged effects roll back when the nested call fails.

events-and-returns

Demonstrates ABI-defined input, structured return values, deterministic status fields, and an event schema. It is useful when designing caller-facing contract methods.

Customize:

• input required fields;
• output object shape;
• event topic approval.completed;
• status vocabulary;
• caller policy.

Keep event and return schemas stable. If UI or indexer code depends on them, treat schema changes as a package version change.

migration-enabled

Demonstrates a normal v2 method plus a contract-defined migration export. The manifest includes migration id v1-to-v2, fromVersion, toVersion, maxBatchSize, and maxFuel.

Customize:

• migration id;
• source and target versions;
• batch size;
• fuel limit;
• transformed keys and values;
• migration event topic.

Migration exports return MigrationOutput; they do not write target storage directly. The migration job engine validates the output and applies writes through resumable batches. See Manifest Migrations.

Copy And Customize Workflow

1. List templates.
2. Copy the closest template to a new directory.
3. Rename package and manifest identifiers.
4. Edit assembly/index.ts.
5. Edit package/manifest.json.
6. Update package/examples/*.json.
7. Build the WASM.
8. Package the contract.
9. Sign the package descriptor when provenance is required.
10. Generate and submit transaction payloads through the publishing workflow.

After copying, update at least:

• manifest name;
• manifest version;
• method names and entrypoints;
• invoke.allow;
• bucket ids, permissions, and availability;
• C2C target contract ids and methods;
• migration ids and version ranges;
• ABI input, output, and event schemas;
• package README and examples.

Build A Copied Template

From inside the copied template directory, build with AssemblyScript:

npx asc assembly/index.ts --outFile build/contract.wasm --textFile build/contract.wat --runtime stub --optimizeLevel 3 --shrinkLevel 1

If you keep the template inside the SDK workspace, you can also adapt the SDK package scripts. For the standard examples, see AssemblyScript SDK.

Package And Publish

The templates are source/package starters. They do not automatically create a network package or submit transactions.

For a production-like flow:

1. Build build/contract.wasm.
2. Package the manifest and WASM into a NOOS contract package.
3. Verify noos-contract.json has the correct codeHash and manifestHash.
4. Sign the package descriptor if provenance is required.
5. Register the package if registry approval is required.
6. Submit transaction DEPLOY_CONTRACT_CODE.
7. Submit transaction INSTANTIATE_CONTRACT.
8. Submit transaction ADD_BUCKET_ACCESS_RULE for the deployed contract principal when the manifest uses buckets.
9. Submit transaction CALL_CONTRACT for method calls.

The end-to-end flow is covered in Publishing.

Before Publishing

Review these gates before using a copied template beyond local development:

• manifest hash matches the reviewed package/manifest.json;
• WASM hash matches the reviewed build artifact;
• method invoke.allow is no broader than intended;
• every host bucket operation has a matching manifest bucket requirement;
• bucket access rules exist for the deployed contract principal;
• C2C callers and targets agree on contract ids and method names;
• migration ids and version ranges match the release plan;
• event and return schemas are stable enough for callers;
• package provenance satisfies the active policy;
• contract registry entry exists when registry policy is required.

Next Steps

• AssemblyScript SDK
• Manifests
• Manifest Methods
• Manifest Calls
• Manifest Migrations
• Authorization
• Publishing
• Package Provenance
• Contract Registry
• Security Guide