Andamio Protocol Placeholder Documentation

This document explains how placeholders work in the Andamio protocol documentation system.

Placeholder Types

1. Static Placeholders

These placeholders represent fixed protocol addresses and policy IDs that are deployment-specific but remain constant once deployed.

Resolution: Values come from deployments/{network}-{version}/params.yaml

Examples:

• <global_state_address> → Fixed address of the global state validator
• <access_token_policyid> → Fixed policy ID for access tokens
• <instance_admin_policyid> → Fixed policy ID for instance admin tokens

2. Dynamic Placeholders

These placeholders are resolved at runtime based on the specific context of the transaction or entity.

Resolution: Values are determined during transaction execution

Examples:

• <alias> → User-specific identifier (e.g., username or ID)
• <module_code> → Course module identifier
• <escrow_hash> → Hash of a specific escrow configuration
• <course_id> → Unique identifier for a course instance
• <project_id> → Unique identifier for a project instance

3. Instance-Specific Placeholders

These represent addresses and policies for dynamically created course and project instances.

Resolution: Values come from deployments/{network}-{version}/examples.yaml for documentation examples

Examples:

• Course validators: assignment_validator_address, course_state_validator_address
• Project validators: contributor_state_scripts_address, treasury_scripts_address

Asset ID Construction Patterns

The protocol uses specific numeric suffixes in asset IDs to distinguish token types:

Suffix Meanings

• .222 - Standard access tokens (e.g., <access_token_policyid>.222<alias>)
• .100 - NFT tokens (e.g., <course_nft_policyid>.100<course_id>)
• .course-state - Course state tokens
• .module-<module_code> - Module-specific tokens
• .treasury - Treasury tokens
• .contributor-state-<contributor> - Contributor state tokens

Special Patterns

Access Token Index

The access-token-index uses a unique escaped pattern:

asset-id: "<access_token_policyid>.\\<index\\>"

The backslashes escape the angle brackets, indicating this is a literal pattern rather than a placeholder.

Usage Guidelines

In Transaction YAML Files

1. Use dot notation for references: global-state.access-token-user
2. Dynamic values appear in contexts like:

   value:
     - "1 <course_nft_policyid>.100<course_id>"
   datum:
     courseId: "<course_id>"

In Registry YAML

1. Define patterns with placeholders:

   tokens:
     access-token-user:
       asset-id: "<access_token_policyid>.222<alias>"

In Deployment Params

1. Only include static values:

   global_state_address: "addr1x84ulqv..."
   access_token_policyid: "e760308d..."

Best Practices

1. Consistency: Always use the same placeholder name across all files
2. Documentation: Comment when a placeholder's resolution is non-obvious
3. Validation: Use the validation script to ensure all static placeholders have corresponding params
4. Examples: Provide concrete examples in examples.yaml for dynamic instances

Common Patterns by Transaction Type

Minting Transactions

• Often use dynamic placeholders for the minted asset (e.g., <alias>, <course_id>)
• Policy ID comes from static params

State Update Transactions

• Reference specific instances using dynamic placeholders
• Validator addresses depend on whether it's a protocol-level or instance-level operation

Multi-Instance Transactions

• Course and project transactions use instance-specific placeholders
• Examples should show typical values from real deployments