{"id":19610841,"url":"https://github.com/onflow/flow-interaction-template-service","last_synced_at":"2025-09-01T01:32:44.129Z","repository":{"id":55525084,"uuid":"515390322","full_name":"onflow/flow-interaction-template-service","owner":"onflow","description":null,"archived":false,"fork":false,"pushed_at":"2025-07-28T19:12:21.000Z","size":2013,"stargazers_count":10,"open_issues_count":24,"forks_count":5,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-07-28T19:14:28.483Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://flix.flow.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/onflow.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":"auditors/README.md","citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-07-19T01:09:00.000Z","updated_at":"2025-07-28T19:06:48.000Z","dependencies_parsed_at":"2023-01-29T18:00:51.333Z","dependency_job_id":"16453db7-4de3-4463-a1cc-f0d7084a8d61","html_url":"https://github.com/onflow/flow-interaction-template-service","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/onflow/flow-interaction-template-service","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onflow%2Fflow-interaction-template-service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onflow%2Fflow-interaction-template-service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onflow%2Fflow-interaction-template-service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onflow%2Fflow-interaction-template-service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/onflow","download_url":"https://codeload.github.com/onflow/flow-interaction-template-service/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onflow%2Fflow-interaction-template-service/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273064362,"owners_count":25039259,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-31T02:00:09.071Z","response_time":79,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-11T10:34:00.348Z","updated_at":"2025-09-01T01:32:44.123Z","avatar_url":"https://github.com/onflow.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Flow Interaction Template Service\n\nThis Flow Interaction Template Service provides a way to propose, store and host `InteractionTemplate` data structures using an efficient in-memory storage system.\n\n## Overview\n\nThis repository is a place for developers to propose their Interaction Templates to be audited, and where Interaction Templates can be stored and hosted by the provided API. The service uses an in-memory storage system that loads all templates at startup for fast, efficient access.\n\n## Architecture\n\n### In-Memory Storage System\nThe service uses a high-performance in-memory storage system that:\n- Loads templates at startup from the `./templates` directory\n- Stores templates in hash maps for O(1) lookup performance  \n- Supports 580+ templates with only ~12MB memory usage\n- Eliminates database dependencies for simplified deployment\n- Optimized for serverless environments like Vercel\n\n### Template Loading\nTemplates are automatically loaded from:\n- Local template files in `./templates/**/*.json`\n- Remote peer instances (if configured via `PEERS` environment variable)\n- Existing manifest files for backward compatibility\n\n### API Endpoints\nThe service provides a RESTful API with the following endpoints:\n\n#### Template Operations\n- `GET /v1/templates/{template_id}` - Get template by ID\n- `GET /v1/templates?name={name}` - Get template by name alias  \n- `GET /v1/templates/manifest` - Get complete template manifest\n- `POST /v1/templates/search` - Search templates by Cadence AST hash\n\n#### Auditor Operations  \n- `GET /v1/auditors?network={network}` - Get auditors for network (mainnet/testnet)\n\n#### Documentation\n- `GET /` - Interactive API documentation homepage\n\n\u003ca name=\"propose\"\u003e\u003c/a\u003e\n\n## Propose Interaction Template\n\nIf you have created an Interaction Template, you can create a PR to place your Interaction Template in the `./proposals` folder of this repository.\n\nAuditors in the Flow ecosystem can check this folder to see new Interaction Templates available for audit.\n\n## Store Interaction Templates\n\nIf you have created an Interaction Template, you can create a PR to place your Interaction Template in the `./templates` folder of this repository. Templates are automatically loaded into memory when the service starts.\n\n## Host Interaction Templates\n\n### Query by Template ID\n```http\nGET /v1/templates/${template_id}\n```\nReturns the complete InteractionTemplate JSON object.\n\n### Search by Cadence Code\n```http\nPOST /v1/templates/search\nContent-Type: application/json\n\n{\n  \"cadence_base64\": \"base64-encoded-cadence-code\",\n  \"network\": \"mainnet\" | \"testnet\"\n}\n```\nReturns the InteractionTemplate that matches the provided Cadence AST hash.\n\n### Query by Name Alias\n```http\nGET /v1/templates?name=transfer-flow\n```\nReturns the InteractionTemplate associated with the given name alias.\n\n### Get Template Manifest\n```http\nGET /v1/templates/manifest\n```\nReturns the complete manifest of all available templates.\n\n### Get Auditors\n```http\nGET /v1/auditors?network=mainnet\n```\nReturns auditor information for the specified network.\n\n## Deployment\n\n### Vercel\nThe service is optimized for serverless deployment on Vercel:\n\n1. No database setup required - templates are loaded from the filesystem\n2. Fast cold starts - templates load in 1-2 seconds\n3. Efficient memory usage - only ~12MB for 580+ templates\n4. Simple build process - single TypeScript compilation step\n\nRequired environment variables:\n```bash\nNODE_ENV=production\nFLOW_ACCESS_API_URL=https://rest-mainnet.onflow.org\nAUDITORS_JSON_FILE=./auditors/auditors.json\nNAMES_JSON_FILE=./names/names.json  \nTEMPLATE_DIR=./templates\nFLOW_NETWORK=mainnet\nDISCOVERY_WALLET=https://fcl-discovery.onflow.org/mainnet/authn\n```\n\n### Other Platforms\nThe service can run on any Node.js hosting platform:\n```bash\nnpm install\nnpm run build\nnpm start\n```\n\n## Development\n\n### Prerequisites\n- Node.js 18.x\n- npm\n\n### Setup\n```bash\n# Install dependencies\nnpm install\n\n# Development mode with auto-reload\nnpm run dev\n\n# Build production version  \nnpm run build\n\n# Start production server\nnpm start\n```\n\n### Project Structure\n```\n├── api/                             # Vercel serverless functions\n│   └── index.ts                     # Main serverless function entry point\n├── src/                             # Source code\n│   ├── storage/                     # In-memory storage system\n│   │   └── InMemoryTemplateStorage.ts\n│   ├── services/                    # Business logic layer\n│   │   └── template.ts\n│   ├── routes/                      # API route definitions\n│   │   ├── template.ts              # Template endpoints\n│   │   └── auditors.ts              # Auditor endpoints  \n│   ├── middlewares/                 # Express middleware\n│   │   └── cors.ts\n│   ├── utils/                       # Utility functions\n│   │   ├── crypto-polyfill.ts\n│   │   ├── gen-hash.ts\n│   │   ├── mixpanel.ts\n│   │   ├── parse-cadence.ts\n│   │   ├── read-files.ts\n│   │   └── write-file.ts\n│   ├── app.ts                       # Express app configuration\n│   ├── index.ts                     # Development server entry\n│   └── config.ts                    # Configuration management\n├── templates/                       # Template storage directory\n│   ├── NFTCatalog/                  # NFT catalog templates\n│   │   └── catalog-manifest.json    # Template catalog manifest\n│   ├── FlowCore/                    # Core Flow templates  \n│   ├── EmeraldID/                   # EmeraldID templates\n│   ├── test/                        # Test templates\n│   └── *.template.json              # Individual template files\n├── auditors/                        # Auditor configuration\n│   └── auditors.json                # Network-specific auditor information\n├── names/                           # Name alias mappings\n│   └── names.json                   # Template name aliases\n├── proposals/                       # Proposed templates for review\n├── vercel.json                      # Vercel deployment configuration\n├── tsconfig.json                    # TypeScript configuration\n├── package.json                     # Dependencies and scripts\n└── .nvmrc                          # Node.js version specification\n```\n\n### Configuration Files\n- **`vercel.json`** - Vercel deployment configuration with serverless function setup\n- **`tsconfig.json`** - TypeScript compilation settings\n- **`package.json`** - Dependencies and build scripts\n- **`auditors/auditors.json`** - Network-specific auditor information\n- **`names/names.json`** - Name aliases for template lookup\n- **Template files** - Individual `.template.json` files containing InteractionTemplate data\n\n## Live Service\n\nFlow's official Interaction Template service is available at:\n```\nhttps://flix.flow.com\n```\n\nExample requests:\n```bash\n# Get template by name\ncurl \"https://flix.flow.com/v1/templates?name=transfer-flow\"\n\n# Get template by ID  \ncurl \"https://flix.flow.com/v1/templates/{template_id}\"\n\n# Search by Cadence code\ncurl -X POST \"https://flix.flow.com/v1/templates/search\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"cadence_base64\": \"...\", \"network\": \"mainnet\"}'\n\n# Get auditors\ncurl \"https://flix.flow.com/v1/auditors?network=mainnet\"\n```\n\n## Open to Anyone\n\nThis project is open to be run by anyone. By forking this repository and deploying the API service, anyone can run an instance of FLIX and make Interaction Templates available for querying.\n\nIf you don't wish to operate your own instance of FLIX, you can use Flow's official instance at `https://flix.flow.com`. To add Interaction Templates to Flow's instance, follow the [Propose Templates](#propose) workflow above.\n\n## Performance Characteristics\n\n- **Startup Time**: 1-2 seconds to load 580+ templates\n- **Memory Usage**: ~12MB total (1.2% of typical serverless limits)\n- **Lookup Performance**: O(1) hash map lookups\n- **Template Count**: Currently supporting 580+ templates\n- **Data Size**: ~7.5MB of template data\n\n## Features\n\n- In-memory storage for maximum performance\n- Serverless-optimized architecture  \n- Zero database dependencies\n- Fast cold starts on Vercel\n- Template validation using Flow's InteractionTemplateUtils\n- Automatic manifest generation\n- CORS-enabled for browser usage\n- TypeScript for type safety\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonflow%2Fflow-interaction-template-service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fonflow%2Fflow-interaction-template-service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonflow%2Fflow-interaction-template-service/lists"}