{"id":31204276,"url":"https://github.com/levicook/arch-token-metadata","last_synced_at":"2025-09-20T16:04:56.115Z","repository":{"id":309248720,"uuid":"1033981773","full_name":"levicook/arch-token-metadata","owner":"levicook","description":null,"archived":false,"fork":false,"pushed_at":"2025-09-19T13:54:57.000Z","size":385,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-19T15:46:44.371Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/levicook.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/SECURITY.md","support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-07T16:42:21.000Z","updated_at":"2025-09-19T13:55:01.000Z","dependencies_parsed_at":"2025-09-04T02:24:41.844Z","dependency_job_id":"97e29846-f79f-4419-bf4b-ec3fa6654bb0","html_url":"https://github.com/levicook/arch-token-metadata","commit_stats":null,"previous_names":["levicook/arch-token-metadata"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/levicook/arch-token-metadata","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/levicook%2Farch-token-metadata","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/levicook%2Farch-token-metadata/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/levicook%2Farch-token-metadata/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/levicook%2Farch-token-metadata/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/levicook","download_url":"https://codeload.github.com/levicook/arch-token-metadata/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/levicook%2Farch-token-metadata/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276119600,"owners_count":25588487,"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-09-20T02:00:10.207Z","response_time":63,"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":"2025-09-20T16:03:57.287Z","updated_at":"2025-09-20T16:04:56.105Z","avatar_url":"https://github.com/levicook.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Arch Token Metadata\n\nLightweight, fast, and standards-minded metadata program for the Arch Network with Rust and TypeScript SDKs. This README focuses on using the program and SDKs, with a concise maintenance section at the end.\n\n### What you can do\n\n- Create core token metadata: name, symbol, image URI, description\n- Update metadata (when not immutable)\n- Attach and replace extensible attributes (key/value pairs)\n- Transfer update authority or make metadata immutable\n\nCore account and PDA seeds:\n\n- `TokenMetadata` PDA: seed `\"metadata\"`\n- `TokenMetadataAttributes` PDA: seed `\"attributes\"`\n\nProgram ID (baked): returned by `arch_token_metadata::id()` and `metadataProgramId()` in SDKs. You can override with `PROGRAM_ID` in env for local deployments.\n\n## Quickstart (localnet)\n\n### Prerequisites\n\n- Docker + Docker Compose\n- Rust toolchain\n- Node.js (for the TS SDK and TS tour)\n\n### 1) Launch local stack and generate a funded payer\n\n```bash\n./examples/launch.sh\n```\n\nThis starts `bitcoind`, `titan`, and `local_validator`, waits for RPC readiness, optionally builds the program ELF, deploys via the setup tool, and writes `examples/.env` with:\n\n- `ARCH_RPC` (e.g. http://localhost:9002)\n- `PAYER_PRIVKEY`, `PAYER_PUBKEY`\n- `MINT_PRIVKEY`, `MINT_PUBKEY` (example)\n- `PROGRAM_ID` (set when a local program is deployed by the setup tool)\n\n### 2a) Run the Rust tour (end-to-end)\n\n```bash\ncargo run -p arch_token_metadata_tour\n```\n\nWhat it does:\n\n- Builds `[optional compute_budget], create_mint_account, initialize_mint2(decimals=9), create_metadata, create_attributes`\n- Signs and submits the transaction\n- Waits for processed status and verifies on-chain accounts via the Reader\n\nEnvironment flags (optional):\n\n- `CU_UNITS` – compute unit limit to request\n- `HEAP_BYTES` – requested heap frame bytes\n\nNote: current runtime does not enforce compute budget requests; helpers are included for forward-compatibility.\n\n### 2b) Run the TypeScript tour (end-to-end)\n\n```bash\nnpm run build -w examples/arch-token-metadata-tour-ts\nnpm run start -w examples/arch-token-metadata-tour-ts\n```\n\nIt performs an equivalent single-transaction flow and verifies metadata via the Reader.\n\n## Using the SDKs\n\n### Rust SDK\n\n```rust\nuse arch_program::pubkey::Pubkey;\nuse arch_token_metadata_sdk::{TokenMetadataClient, CreateMetadataParams};\n\nlet program_id: Pubkey = arch_token_metadata::id();\nlet client = TokenMetadataClient::new(program_id);\n\nlet ix = client.create_metadata_ix(CreateMetadataParams {\n    payer,\n    mint,\n    mint_or_freeze_authority: payer,\n    name: \"MyToken\".into(),\n    symbol: \"MTK\".into(),\n    image: \"https://example.com/logo.png\".into(),\n    description: \"hello\".into(),\n    immutable: false,\n})?;\n```\n\nCommon transaction builders:\n\n- `create_token_with_metadata_tx`\n- `create_token_with_metadata_and_attributes_tx`\n- `create_token_with_freeze_auth_metadata_tx`\n- Budget-aware variants: `*_tx_with_budget`\n\nReaders:\n\n- `get_token_metadata(mint)`\n- `get_token_metadata_attributes(mint)`\n- `get_token_details(mint)`\n\nValidation limits (mirrors on-chain):\n\n- `NAME_MAX_LEN=256`, `SYMBOL_MAX_LEN=16`, `IMAGE_MAX_LEN=512`, `DESCRIPTION_MAX_LEN=512`\n- Attributes: `MAX_ATTRIBUTES=32`, `MAX_KEY_LENGTH=64`, `MAX_VALUE_LENGTH=240`\n\n### TypeScript SDK\n\nInstall in your app:\n\n```bash\nnpm install arch-token-metadata-sdk @saturnbtcio/arch-sdk\n```\n\nUsage:\n\n```ts\nimport {\n  TokenMetadataClient,\n  metadataProgramId,\n} from \"arch-token-metadata-sdk\";\n\nconst client = new TokenMetadataClient(metadataProgramId());\nconst ix = client.createMetadataIx({\n  payer,\n  mint,\n  mintOrFreezeAuthority: payer,\n  name: \"MyToken\",\n  symbol: \"MTK\",\n  image: \"https://example.com/logo.png\",\n  description: \"hello\",\n  immutable: false,\n});\n// Compose with your token minting instructions, build a message with @saturnbtcio/arch-sdk, sign (e.g., BIP-322), and submit\n```\n\nConvenience builders (all return `Instruction[]`):\n\n- `createTokenWithMetadataTx`\n- `createTokenWithMetadataAndAttributesTx`\n- `createTokenWithFreezeAuthMetadataTx`\n- Budget-aware: `...WithBudget` variants\n\nReader helpers:\n\n- `getTokenMetadata(mint)`\n- `getTokenMetadataAttributes(mint)`\n- `getTokenDetails(mint)`\n\n## Program instruction set\n\n- CreateMetadata { name, symbol, image, description, immutable }\n- UpdateMetadata { name?, symbol?, image?, description? }\n- CreateAttributes { data: Vec\u003c(String, String)\u003e }\n- ReplaceAttributes { data: Vec\u003c(String, String)\u003e }\n- TransferAuthority { new_authority }\n- MakeImmutable\n\nAuthority model:\n\n- Create: mint authority, or freeze authority if mint authority is None\n- A unified update authority controls both metadata and attributes\n- `MakeImmutable` revokes update authority permanently\n\n## Repo layout\n\n- `programs/arch-token-metadata` – on-chain program\n- `sdks/arch-token-metadata-sdk-rs` – Rust SDK\n- `sdks/arch-token-metadata-sdk-ts` – TypeScript SDK\n- `examples/arch-token-metadata-tour-rs` – Rust end-to-end tour\n- `examples/arch-token-metadata-tour-ts` – TypeScript end-to-end tour\n- `program-tests/arch-token-metadata-tests` – integration tests\n- `benchmarks/token-metadata-benches` – CU benchmarks\n- `docs/` – status, roadmap, security, and benchmarks report\n\n## Maintenance\n\n### Build program (optional, local deploy)\n\n`examples/launch.sh` attempts to build an ELF for local deploy. Manually:\n\n```bash\ncargo build-sbf --manifest-path programs/arch-token-metadata/Cargo.toml --sbf-out-dir examples/.tmp/.sbf-out\n```\n\nSet `PROGRAM_ID` in your env when submitting transactions against a locally deployed program.\n\n### Tests\n\nRust integration tests:\n\n```bash\ncargo test -p arch-token-metadata-tests -- --nocapture\n```\n\nTypeScript SDK tests (will regenerate golden fixtures):\n\n```bash\ncargo run -p arch_token_metadata_fixtures\nnpm run test -w sdks/arch-token-metadata-sdk-ts\n```\n\n### Benchmarks\n\n```bash\ncargo run -p token-metadata-benches\n```\n\nSee benchmark notes in `docs/benchmarks/README.md` and `docs/benchmarks/report.json`.\n\n### Security, roadmap, implementation status\n\n- Security invariants: see `docs/SECURITY.md`\n- Implementation status vs proposal: see `docs/IMPLEMENTATION_STATUS.md`\n- Roadmap: see `docs/ROADMAP.md`\n\n### Notes on compute budget\n\nThe SDKs can prepend compute budget instructions (SetComputeUnitLimit, RequestHeapFrame). Current runtime does not enforce these requests yet; effective limits remain defaults. Keep helpers in flows for forward-compatibility.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flevicook%2Farch-token-metadata","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flevicook%2Farch-token-metadata","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flevicook%2Farch-token-metadata/lists"}