8004-solana-sdk

Category: Development & Coding | Uploader: QuantuLabs | Downloads: 0 | Version: v1.0（Latest）

TypeScript SDK for the 8004 Trustless Agent Registry on Solana. Covers agent registration, feedback/SEAL v1, ATOM reputation engine, signing, indexer queries, x402 payment feedback, and skipSend server-mode patterns.

Changelog: Source: GitHub https://github.com/QuantuLabs/8004-solana-ts

Directory Structure

Current level: Root

📁 .claude/
- 📄 CLAUDE.md 2.8 KB
📁 dist/
- 📁 core/
  - 📄 agent-mint-resolver.d.ts 3.0 KB
  - 📄 agent-mint-resolver.d.ts.map 1.2 KB
  - 📄 agent-mint-resolver.js 7.1 KB
  - 📄 agent-mint-resolver.js.map 4.1 KB
  - 📄 atom-pda.d.ts 1.4 KB
  - 📄 atom-pda.d.ts.map 589 B
  - 📄 atom-pda.js 1.8 KB
  - 📄 atom-pda.js.map 1019 B
  - 📄 atom-schemas.d.ts 7.2 KB
  - 📄 atom-schemas.d.ts.map 5.1 KB
  - 📄 atom-schemas.js 20.7 KB
  - 📄 atom-schemas.js.map 13.7 KB
  - 📄 borsh-schemas.d.ts 8.4 KB
  - 📄 borsh-schemas.d.ts.map 5.4 KB
  - 📄 borsh-schemas.js 28.9 KB
  - 📄 borsh-schemas.js.map 19.6 KB
  - 📄 client.d.ts 4.4 KB
  - 📄 client.d.ts.map 2.2 KB
  - 📄 client.js 8.0 KB
  - 📄 client.js.map 5.0 KB
  - 📄 config-reader.d.ts 2.5 KB
  - 📄 config-reader.d.ts.map 985 B
  - 📄 config-reader.js 3.8 KB
  - 📄 config-reader.js.map 2.2 KB
  - 📄 endpoint-crawler.d.ts 1.2 KB
  - 📄 endpoint-crawler.d.ts.map 699 B
  - 📄 endpoint-crawler.js 13.3 KB
  - 📄 endpoint-crawler.js.map 9.8 KB
  - 📄 feedback-manager-solana.d.ts 7.6 KB
  - 📄 feedback-manager-solana.d.ts.map 2.8 KB
  - 📄 feedback-manager-solana.js 17.4 KB
  - 📄 feedback-manager-solana.js.map 9.8 KB
  - 📄 feedback-normalizer.d.ts 1.3 KB
  - 📄 feedback-normalizer.d.ts.map 653 B
  - 📄 feedback-normalizer.js 2.8 KB
  - 📄 feedback-normalizer.js.map 2.0 KB
  - 📄 hash-chain-replay.d.ts 3.7 KB
  - 📄 hash-chain-replay.d.ts.map 2.1 KB
  - 📄 hash-chain-replay.js 8.1 KB
  - 📄 hash-chain-replay.js.map 6.4 KB
  - 📄 indexer-client.d.ts 21.8 KB
  - 📄 indexer-client.d.ts.map 16.4 KB
  - 📄 indexer-client.js 45.3 KB
  - 📄 indexer-client.js.map 36.3 KB
  - 📄 indexer-defaults.d.ts 1.5 KB
  - 📄 indexer-defaults.d.ts.map 660 B
  - 📄 indexer-defaults.js 3.1 KB
  - 📄 indexer-defaults.js.map 1.8 KB
  - 📄 indexer-errors.d.ts 1.3 KB
  - 📄 indexer-errors.d.ts.map 757 B
  - 📄 indexer-errors.js 2.0 KB
  - 📄 indexer-errors.js.map 1.3 KB
  - 📄 indexer-graphql-client.d.ts 4.6 KB
  - 📄 indexer-graphql-client.d.ts.map 4.0 KB
  - 📄 indexer-graphql-client.js 60.6 KB
  - 📄 indexer-graphql-client.js.map 46.9 KB
  - 📄 indexer-types.d.ts 3.5 KB
  - 📄 indexer-types.d.ts.map 2.1 KB
  - 📄 indexer-types.js 3.2 KB
  - 📄 indexer-types.js.map 2.3 KB
  - 📄 instruction-builder.d.ts 12.6 KB
  - 📄 instruction-builder.d.ts.map 5.8 KB
  - 📄 instruction-builder.js 32.8 KB
  - 📄 instruction-builder.js.map 23.4 KB
  - 📄 instruction-discriminators.d.ts 3.8 KB
  - 📄 instruction-discriminators.d.ts.map 566 B
  - 📄 instruction-discriminators.js 5.2 KB
  - 📄 instruction-discriminators.js.map 6.1 KB
  - 📄 ipfs-client.d.ts 3.4 KB
  - 📄 ipfs-client.d.ts.map 1.6 KB
  - 📄 ipfs-client.js 25.2 KB
  - 📄 ipfs-client.js.map 18.7 KB
  - 📄 metaplex-helpers.d.ts 894 B
  - 📄 metaplex-helpers.d.ts.map 432 B
  - 📄 metaplex-helpers.js 1.4 KB
  - 📄 metaplex-helpers.js.map 981 B
  - 📄 oasf-data.d.ts 870 B
  - 📄 oasf-data.d.ts.map 370 B
  - 📄 oasf-data.js 17.4 KB
  - 📄 oasf-data.js.map 4.8 KB
  - 📄 oasf-validator.d.ts 1005 B
  - 📄 oasf-validator.d.ts.map 373 B
  - 📄 oasf-validator.js 1.1 KB
  - 📄 oasf-validator.js.map 550 B
  - 📄 pda-helpers.d.ts 4.1 KB
  - 📄 pda-helpers.d.ts.map 2.2 KB
  - 📄 pda-helpers.js 6.7 KB
  - 📄 pda-helpers.js.map 4.3 KB
  - 📄 programs.d.ts 4.5 KB
  - 📄 programs.d.ts.map 1.5 KB
  - 📄 programs.js 6.3 KB
  - 📄 programs.js.map 4.1 KB
  - 📄 sdk-solana.d.ts 47.1 KB
  - 📄 sdk-solana.d.ts.map 17.4 KB
  - 📄 sdk-solana.js 138.5 KB
  - 📄 sdk-solana.js.map 91.8 KB
  - 📄 seal.d.ts 3.5 KB
  - 📄 seal.d.ts.map 1.2 KB
  - 📄 seal.js 6.9 KB
  - 📄 seal.js.map 5.3 KB
  - 📄 transaction-builder.d.ts 18.3 KB
  - 📄 transaction-builder.d.ts.map 7.2 KB
  - 📄 transaction-builder.js 73.1 KB
  - 📄 transaction-builder.js.map 49.8 KB
  - 📄 utils.d.ts 647 B
  - 📄 utils.d.ts.map 274 B
  - 📄 utils.js 1.1 KB
  - 📄 utils.js.map 669 B
- 📁 models/
  - 📄 collection-metadata.d.ts 2.8 KB
  - 📄 collection-metadata.d.ts.map 2.0 KB
  - 📄 collection-metadata.js 4.0 KB
  - 📄 collection-metadata.js.map 4.0 KB
  - 📄 enums.d.ts 657 B
  - 📄 enums.d.ts.map 442 B
  - 📄 enums.js 810 B
  - 📄 enums.js.map 520 B
  - 📄 index.d.ts 306 B
  - 📄 index.d.ts.map 256 B
  - 📄 index.js 304 B
  - 📄 index.js.map 254 B
  - 📄 interfaces.d.ts 4.9 KB
  - 📄 interfaces.d.ts.map 4.0 KB
  - 📄 interfaces.js 91 B
  - 📄 interfaces.js.map 132 B
  - 📄 liveness.d.ts 1.0 KB
  - 📄 liveness.d.ts.map 1015 B
  - 📄 liveness.js 102 B
  - 📄 liveness.js.map 128 B
  - 📄 signatures.d.ts 466 B
  - 📄 signatures.d.ts.map 548 B
  - 📄 signatures.js 104 B
  - 📄 signatures.js.map 132 B
  - 📄 types.d.ts 278 B
  - 📄 types.d.ts.map 375 B
  - 📄 types.js 83 B
  - 📄 types.js.map 122 B
- 📁 utils/
  - 📄 buffer-utils.d.ts 1.6 KB
  - 📄 buffer-utils.d.ts.map 595 B
  - 📄 buffer-utils.js 2.6 KB
  - 📄 buffer-utils.js.map 1.8 KB
  - 📄 canonical-json.d.ts 273 B
  - 📄 canonical-json.d.ts.map 329 B
  - 📄 canonical-json.js 1.0 KB
  - 📄 canonical-json.js.map 1.2 KB
  - 📄 compression.d.ts 1.3 KB
  - 📄 compression.d.ts.map 385 B
  - 📄 compression.js 4.4 KB
  - 📄 compression.js.map 2.7 KB
  - 📄 constants.d.ts 1.4 KB
  - 📄 constants.d.ts.map 360 B
  - 📄 constants.js 1.4 KB
  - 📄 constants.js.map 1017 B
  - 📄 crypto-utils.d.ts 1.3 KB
  - 📄 crypto-utils.d.ts.map 537 B
  - 📄 crypto-utils.js 3.3 KB
  - 📄 crypto-utils.js.map 2.2 KB
  - 📄 e2e-indexers-runlog.d.ts 3.2 KB
  - 📄 e2e-indexers-runlog.d.ts.map 2.3 KB
  - 📄 e2e-indexers-runlog.js 7.2 KB
  - 📄 e2e-indexers-runlog.js.map 6.8 KB
  - 📄 index.d.ts 397 B
  - 📄 index.d.ts.map 347 B
  - 📄 index.js 395 B
  - 📄 index.js.map 345 B
  - 📄 logger.d.ts 713 B
  - 📄 logger.d.ts.map 610 B
  - 📄 logger.js 3.2 KB
  - 📄 logger.js.map 3.2 KB
  - 📄 registration-file-builder.d.ts 655 B
  - 📄 registration-file-builder.d.ts.map 435 B
  - 📄 registration-file-builder.js 4.5 KB
  - 📄 registration-file-builder.js.map 3.7 KB
  - 📄 signing.d.ts 975 B
  - 📄 signing.d.ts.map 830 B
  - 📄 signing.js 5.7 KB
  - 📄 signing.js.map 5.9 KB
  - 📄 tags.d.ts 3.3 KB
  - 📄 tags.d.ts.map 750 B
  - 📄 tags.js 5.9 KB
  - 📄 tags.js.map 2.0 KB
  - 📄 validation.d.ts 993 B
  - 📄 validation.d.ts.map 752 B
  - 📄 validation.js 7.8 KB
  - 📄 validation.js.map 7.3 KB
  - 📄 value-encoding.d.ts 1.5 KB
  - 📄 value-encoding.d.ts.map 564 B
  - 📄 value-encoding.js 7.8 KB
  - 📄 value-encoding.js.map 7.1 KB
- 📄 index.d.ts 4.0 KB
- 📄 index.d.ts.map 2.5 KB
- 📄 index.js 3.9 KB
- 📄 index.js.map 2.0 KB
📁 docs/
- 📄 CHANGELOG.md 3.6 KB
- 📄 COLLECTION.md 3.4 KB
- 📄 COSTS.md 801 B
- 📄 FEEDBACK.md 8.9 KB
- 📄 METHODS.md 28.7 KB
- 📄 OASF.md 17.0 KB
- 📄 quickstart.html 12.2 KB
- 📄 QUICKSTART.md 7.2 KB
📁 examples/
- 📄 agent-update.ts 3.9 KB
- 📄 collection-flow.ts 7.4 KB
- 📄 feedback-usage.ts 4.5 KB
- 📄 quick-start.ts 4.4 KB
- 📄 server-mode.ts 8.4 KB
- 📄 transfer-agent.ts 2.0 KB
📁 schemas/
- 📁 examples/
  - 📄 agent-example.json 1.3 KB
  - 📄 collection-example.json 601 B
- 📄 agent-metadata.schema.json 3.8 KB
- 📄 collection-metadata.schema.json 3.7 KB
📁 scripts/
- 📄 audit-codex.sh 4.4 KB
- 📄 check-collection.ts 2.4 KB
- 📄 check-registry-config.ts 1.8 KB
- 📄 e2e-indexer-test.ts 7.2 KB
- 📄 e2e-indexers-check.mjs 33.6 KB
- 📄 e2e-indexers-check.test.mjs 10.9 KB
- 📄 e2e-indexers-compare.mjs 2.4 KB
- 📄 e2e-indexers-docker-hook.mjs 2.6 KB
- 📄 e2e-indexers-ipfs-start.mjs 4.2 KB
- 📄 e2e-indexers-ipfs-stop.mjs 1.8 KB
- 📄 e2e-indexers-lib.mjs 15.0 KB
- 📄 e2e-indexers-lib.test.mjs 1.6 KB
- 📄 e2e-indexers-matrix.mjs 21.1 KB
- 📄 e2e-indexers-matrix.test.mjs 5.9 KB
- 📄 e2e-indexers-seed-write.mjs 48.0 KB
- 📄 e2e-indexers-seed-write.test.mjs 3.7 KB
- 📄 e2e-test.ts 4.2 KB
- 📄 get-root-config.ts 1.3 KB
- 📄 recover-stress-wallet-sol.mjs 10.0 KB
- 📄 review.sh 1.2 KB
- 📄 stress-sdk-devnet-aggressive.mjs 54.9 KB
- 📄 stress-sdk-devnet-feedback-focus.mjs 1.9 KB
- 📄 test-onchain-full.ts 7.7 KB
- 📄 verify-db-full-integrity.cjs 44.3 KB
- 📄 verify-indexers-strict-integrity.mjs 42.0 KB
- 📄 verify-indexers-strict-integrity.test.mjs 7.2 KB
- 📄 verify-stress-indexers-consistency.mjs 14.9 KB
- 📄 verify-stress-input-integrity.mjs 31.5 KB
📁 src/
- 📁 core/
  - 📄 agent-mint-resolver.ts 7.3 KB
  - 📄 atom-pda.ts 1.9 KB
  - 📄 atom-schemas.ts 21.2 KB
  - 📄 borsh-schemas.ts 30.1 KB
  - 📄 client.ts 8.3 KB
  - 📄 config-reader.ts 4.0 KB
  - 📄 endpoint-crawler.ts 11.9 KB
  - 📄 feedback-manager-solana.ts 18.5 KB
  - 📄 feedback-normalizer.ts 2.9 KB
  - 📄 hash-chain-replay.ts 9.1 KB
  - 📄 indexer-client.ts 57.7 KB
  - 📄 indexer-defaults.ts 3.1 KB
  - 📄 indexer-errors.ts 1.8 KB
  - 📄 indexer-graphql-client.ts 62.6 KB
  - 📄 indexer-types.ts 5.4 KB
  - 📄 instruction-builder.ts 34.3 KB
  - 📄 instruction-discriminators.ts 5.1 KB
  - 📄 ipfs-client.ts 23.2 KB
  - 📄 metaplex-helpers.ts 1.4 KB
  - 📄 oasf-data.ts 16.7 KB
  - 📄 oasf-validator.ts 1.1 KB
  - 📄 pda-helpers.ts 7.4 KB
  - 📄 programs.ts 7.0 KB
  - 📄 sdk-solana.ts 148.8 KB
  - 📄 seal.ts 7.6 KB
  - 📄 transaction-builder.ts 75.4 KB
  - 📄 utils.ts 1.1 KB
- 📁 models/
  - 📄 collection-metadata.ts 6.2 KB
  - 📄 enums.ts 577 B
  - 📄 index.ts 272 B
  - 📄 interfaces.ts 5.7 KB
  - 📄 liveness.ts 964 B
  - 📄 signatures.ts 410 B
  - 📄 types.ts 531 B
- 📁 taxonomies/
  - 📄 all_domains.json 72.9 KB
  - 📄 all_skills.json 46.4 KB
- 📁 utils/
  - 📄 buffer-utils.ts 2.7 KB
  - 📄 canonical-json.ts 1023 B
  - 📄 compression.ts 4.3 KB
  - 📄 constants.ts 1.4 KB
  - 📄 crypto-utils.ts 3.4 KB
  - 📄 e2e-indexers-runlog.ts 9.2 KB
  - 📄 index.ts 364 B
  - 📄 logger.ts 3.3 KB
  - 📄 registration-file-builder.ts 4.7 KB
  - 📄 signing.ts 5.9 KB
  - 📄 tags.ts 5.8 KB
  - 📄 validation.ts 7.4 KB
  - 📄 value-encoding.ts 7.5 KB
- 📄 index.ts 5.6 KB
📁 test-data/
- 📄 compression-test-metadata.json 2.5 KB
📁 tests/
- 📁 e2e-solana/
  - 📄 01-identity-complete.test.ts 17.6 KB
  - 📄 02-reputation-complete.test.ts 28.6 KB
  - 📄 03-validation-complete.test.ts 19.2 KB
  - 📄 04-atom-engine-complete.test.ts 32.3 KB
  - 📄 05-security-attacks.test.ts 24.8 KB
  - 📄 06-indexer-api.test.ts 35.1 KB
  - 📄 07-v050-value-decimals.test.ts 20.6 KB
  - 📄 08-reputation-gaming.test.ts 17.5 KB
  - 📄 09-seal-v1-complete.test.ts 13.0 KB
  - 📄 10-collection-parent-complete.test.ts 6.7 KB
  - 📄 11-indexer-graphql-parity.test.ts 10.3 KB
  - 📄 check-agent.ts 1.9 KB
  - 📄 create-test-agent.ts 1.5 KB
  - 📄 devnet-setup.ts 3.3 KB
  - 📄 e2e-devnet-funded.test.ts 21.2 KB
  - 📄 e2e-devnet-sealhash-indexer.test.ts 13.2 KB
  - 📄 e2e-error-scenarios-localnet.test.ts 10.5 KB
  - 📄 e2e-error-scenarios.test.ts 14.3 KB
  - 📄 e2e-full-flow-localnet.test.ts 13.2 KB
  - 📄 e2e-full-flow.test.ts 20.5 KB
  - 📄 e2e-performance.test.ts 12.6 KB
  - 📄 e2e-sign-verify-localnet.test.ts 7.7 KB
  - 📄 e2e-sign-verify-wallet.test.ts 20.0 KB
  - 📄 e2e-validation-localnet.test.ts 9.0 KB
  - 📄 e2e-validation.test.ts 8.1 KB
  - 📄 integrity-manipulation-test.ts 16.8 KB
  - 📄 README.md 3.2 KB
  - 📄 setup-env.ts 4.1 KB
  - 📄 stress-test-hashchain-localnet.ts 17.8 KB
  - 📄 stress-test-massive.ts 38.9 KB
  - 📄 stress-test-offchain-ipfs.ts 29.5 KB
  - 📄 stress-test-offchain-metadata.ts 16.4 KB
  - 📄 stress-test-ultimate.ts 33.7 KB
  - 📄 test-feedback-debug.ts 1.8 KB
- 📁 integration/
  - 📄 indexer-queries.test.ts 5.0 KB
- 📁 security/
  - 📄 buffer-validation.test.ts 5.0 KB
  - 📄 input-rejection.test.ts 5.0 KB
  - 📄 ssrf-protection.test.ts 5.1 KB
  - 📄 string-validation.test.ts 4.4 KB
  - 📄 transaction-safety.test.ts 4.3 KB
- 📁 unit/
  - 📄 agent-mint-resolver.test.ts 9.4 KB
  - 📄 atom-pda.test.ts 2.4 KB
  - 📄 atom-schemas.test.ts 16.4 KB
  - 📄 borsh-schemas.test.ts 22.9 KB
  - 📄 buffer-utils.test.ts 4.1 KB
  - 📄 canonical-json.test.ts 2.0 KB
  - 📄 client.test.ts 18.9 KB
  - 📄 collection-metadata.test.ts 5.2 KB
  - 📄 collection-methods.test.ts 2.7 KB
  - 📄 compression-full.test.ts 3.9 KB
  - 📄 compression.test.ts 4.1 KB
  - 📄 config-reader.test.ts 7.3 KB
  - 📄 crypto-utils-full.test.ts 2.8 KB
  - 📄 crypto-utils.test.ts 3.5 KB
  - 📄 e2e-indexers-runlog.test.ts 3.5 KB
  - 📄 endpoint-crawler-deep.test.ts 8.1 KB
  - 📄 endpoint-crawler.test.ts 8.8 KB
  - 📄 feedback-manager-full.test.ts 16.9 KB
  - 📄 feedback-manager.test.ts 4.8 KB
  - 📄 feedback-normalizer.test.ts 5.0 KB
  - 📄 hash-chain-replay.test.ts 18.2 KB
  - 📄 indexer-client-full.test.ts 46.2 KB
  - 📄 indexer-client.test.ts 5.1 KB
  - 📄 indexer-graphql-client.test.ts 60.4 KB
  - 📄 indexer-types.test.ts 7.8 KB
  - 📄 instruction-builder.test.ts 27.9 KB
  - 📄 ipfs-client-deep.test.ts 8.7 KB
  - 📄 ipfs-client-extended.test.ts 7.6 KB
  - 📄 ipfs-client.test.ts 10.4 KB
  - 📄 liveness.test.ts 11.0 KB
  - 📄 logger.test.ts 8.0 KB
  - 📄 metaplex-helpers.test.ts 2.4 KB
  - 📄 oasf-validator.test.ts 2.1 KB
  - 📄 pda-helpers.test.ts 9.2 KB
  - 📄 programs.test.ts 5.1 KB
  - 📄 registration-file-builder.test.ts 8.4 KB
  - 📄 sdk-initialization.test.ts 8.3 KB
  - 📄 sdk-solana-deep.test.ts 26.8 KB
  - 📄 sdk-solana-extended.test.ts 32.8 KB
  - 📄 sdk-solana.test.ts 82.0 KB
  - 📄 seal-full.test.ts 7.4 KB
  - 📄 set-agent-wallet.test.ts 2.2 KB
  - 📄 signing-full.test.ts 9.7 KB
  - 📄 signing.test.ts 7.2 KB
  - 📄 tags.test.ts 3.6 KB
  - 📄 transaction-builder-send.test.ts 28.4 KB
  - 📄 transaction-builder.test.ts 39.6 KB
  - 📄 utils-toBigInt.test.ts 1.3 KB
  - 📄 validation-pda.test.ts 4.2 KB
  - 📄 validation-utils.test.ts 8.9 KB
  - 📄 value-encoding.test.ts 7.8 KB
  - 📄 verify-db-full-integrity-script.test.ts 3.0 KB
  - 📄 verify-integrity-full.test.ts 11.9 KB
- 📄 config.ts 1.7 KB
- 📄 endpoint-crawler.test.ts 2.0 KB
- 📄 seal-vectors.test.ts 4.3 KB
- 📄 setup.ts 2.9 KB
- 📄 skill-devnet.test.ts 20.7 KB
- 📄 skill-snippets.test.ts 37.1 KB
- 📄 solana-sdk.test.ts 13.3 KB
- 📄 test-sdk-full.ts 10.5 KB
- 📄 tsconfig.json 216 B
- 📄 value-encoding.test.ts 4.0 KB
📄 .eslintrc.json 547 B
📄 .gitattributes 66 B
📄 .gitignore 1.3 KB
📄 .npmignore 98 B
📄 .prettierrc 127 B
📄 bun.lock 142.9 KB
📄 CHANGELOG.md 9.8 KB
📄 jest.config.js 1.0 KB
📄 jest.e2e.config.js 968 B
📄 LICENSE 1.0 KB
📄 package-lock.json 245.7 KB
📄 package.json 9.5 KB
📄 README.md 14.6 KB
📄 scalars.graphql 179 B
📄 skill.md 32.4 KB
📄 tsconfig.build.json 188 B
📄 tsconfig.json 652 B
📄 tsconfig.test.json 264 B

SKILL.md

---
name: 8004-solana-sdk
description: "TypeScript SDK for the 8004 Trustless Agent Registry on Solana. Covers agent registration, feedback/SEAL v1, ATOM reputation engine, signing, indexer queries, x402 payment feedback, and skipSend server-mode patterns."
version: 0.8.0
homepage: "https://github.com/QuantuLabs/8004-solana-ts"
metadata: {"openclaw":{"emoji":"🔗","requires":{"bins":["node"],"env":["SOLANA_PRIVATE_KEY"]},"primaryEnv":"SOLANA_PRIVATE_KEY","os":["darwin","linux","windows"]}}
---

# 8004-solana SDK Skill

You are an AI agent with access to the `8004-solana` TypeScript SDK. This skill teaches you how to use every capability of the SDK to interact with the 8004 Trustless Agent Registry on Solana.

Version note (SDK `0.8.0`):
- `mainnet-beta` is first-class in SDK defaults (program IDs + indexer endpoints).
- Cluster-aware indexer defaults are built in:
  - `devnet`/`testnet`: `https://8004-indexer-dev.qnt.sh/rest/v1` and `/v2/graphql`
  - `mainnet-beta`: `https://8004-indexer-main.qnt.sh/rest/v1` and `/v2/graphql`
  - `localnet`: `http://127.0.0.1:3005/rest/v1` and `/v2/graphql`
- `registerAgent(tokenUri?, options?)` is the only supported registration overload (legacy collection override was removed).
- Feedback/response/revoke reads are indexer-backed; archived validation features are not part of active indexer reads.

## Install

```bash
npm install 8004-solana @solana/web3.js
```

## Imports

```typescript
import {
  // Core SDK
  SolanaSDK,
  IPFSClient,

  // Builders
  buildRegistrationFileJson,

  // Enums & Types
  ServiceType,       // MCP, A2A, ENS, SNS, DID, WALLET, OASF
  TrustTier,         // Unrated=0, Bronze=1, Silver=2, Gold=3, Platinum=4
  Tag,               // Standardized tag constants

  // ATOM Engine
  AtomStats,
  trustTierToString,

  // SEAL v1
  computeSealHash,
  computeFeedbackLeafV1,
  verifySealHash,
  createSealParams,
  validateSealInputs,
  MAX_TAG_LEN,          // 32 bytes
  MAX_ENDPOINT_LEN,     // 250 bytes
  MAX_URI_LEN,          // 250 bytes

  // OASF Taxonomy
  getAllSkills,
  getAllDomains,

  // Tag helpers
  isKnownTag,
  getTagDescription,

  // Signing
  buildSignedPayload,
  verifySignedPayload,
  parseSignedPayload,
  normalizeSignData,
  createNonce,
  canonicalizeJson,

  // Value encoding
  encodeReputationValue,
  decodeToDecimalString,
  decodeToNumber,

  // Crypto utilities
  keccak256,
  sha256,
  sha256Sync,          // Node.js only

  // Hash-chain replay
  replayFeedbackChain,
  replayResponseChain,
  replayRevokeChain,

  // Indexer
  IndexerClient,

  // Endpoint crawler
  EndpointCrawler,

  // Error classes
  IndexerError,
  IndexerUnavailableError,
  IndexerTimeoutError,
  IndexerRateLimitError,
  UnsupportedRpcError,
  RpcNetworkError,
} from '8004-solana';

import { Keypair, PublicKey } from '@solana/web3.js';
```

---

## 1. SDK Setup

### Read-only (no wallet needed)

```typescript
const sdk = new SolanaSDK({ cluster: 'devnet' });
```

### With signer (for write operations)

```typescript
const signer = Keypair.fromSecretKey(
  Uint8Array.from(JSON.parse(process.env.SOLANA_PRIVATE_KEY!))
);
const sdk = new SolanaSDK({ signer });
```

### With custom RPC (required for bulk queries)

```typescript
const sdk = new SolanaSDK({
  rpcUrl: 'https://your-helius-rpc.helius.dev',
  signer,
});
```

### Network defaults

```typescript
// Mainnet ready defaults
const mainnetSdk = new SolanaSDK({ cluster: 'mainnet-beta', signer });

// Devnet defaults
const devnetSdk = new SolanaSDK({ cluster: 'devnet', signer });

// Localnet (override program IDs to your deployed addresses)
const localnetSdk = new SolanaSDK({
  cluster: 'localnet',
  rpcUrl: 'http://127.0.0.1:8899',
  signer,
  programIds: {
    agentRegistry: '...',
    atomEngine: '...',
  },
});
```

### Full config

```typescript
const sdk = new SolanaSDK({
  cluster: 'mainnet-beta',
  rpcUrl: 'https://...',
  signer: keypair,
  // Optional: explicit overrides (otherwise cluster defaults are used)
  programIds: {
    agentRegistry: '...',
    atomEngine: '...',
  },
  // Optional: force REST mode (omit indexerGraphqlUrl)
  indexerUrl: 'https://8004-indexer-main.qnt.sh/rest/v1',
  indexerApiKey: process.env.INDEXER_API_KEY, // if your indexer requires an API key, keep it in env

  // Or force GraphQL mode instead:
  // indexerGraphqlUrl: 'https://8004-indexer-main.qnt.sh/v2/graphql',
  useIndexer: true,
  indexerFallback: true,
  forceOnChain: false,
});
```

### IPFS client

```typescript
// Pinata (recommended)
const ipfsPinata = new IPFSClient({
  pinataEnabled: true,
  pinataJwt: process.env.PINATA_JWT!,
});

// Local node
const ipfsLocal = new IPFSClient({ url: 'http://localhost:5001' });
```

---

## 2. Register an Agent

### Step 1: Build metadata

```typescript
const metadata = buildRegistrationFileJson({
  name: 'My Agent',
  description: 'Autonomous trading agent',
  image: 'ipfs://QmImageCid...',
  services: [
    { type: ServiceType.MCP, value: 'https://my-agent.com/mcp' },
    { type: ServiceType.A2A, value: 'https://my-agent.com/a2a' },
    { type: ServiceType.SNS, value: 'my-agent.sol' },
  ],
  skills: ['advanced_reasoning_planning/strategic_planning'],
  domains: ['finance_and_business/finance'],
  x402Support: true,
});
```

### Step 2: Upload to IPFS

```typescript
const cid = await ipfs.addJson(metadata);
```

### Step 3: Register on-chain

```typescript
const result = await sdk.registerAgent(`ipfs://${cid}`);
// result.asset   -> PublicKey (agent NFT address)
// result.signature -> transaction signature

// Optional: enable ATOM at creation (irreversible)
const withAtom = await sdk.registerAgent(`ipfs://${cid}`, {
  atomEnabled: true,
});
```

### Step 4: Set operational wallet

```typescript
const opWallet = Keypair.generate();
await sdk.setAgentWallet(result.asset, opWallet);
```

### Collection + Parent Association (CID-first)

All agents register into the base collection automatically. Collection metadata now follows an off-chain CID-first flow:
A collection is unique only when the minting creator is the same and the collection pointer is the same.
For indexer reads, you can also use sequential `collection_id` helpers (`getCollectionPointerById`, `getCollectionAssetCountById`, `getCollectionAssetsById`).

```typescript
const { asset } = result; // from registerAgent(...)

// Build JSON payload (off-chain)
const collectionData = sdk.createCollectionData({
  name: 'CasterCorp Agents',
  symbol: 'CAST',
  description: 'Production agent collection metadata',
});

// Upload and derive canonical pointer
const { pointer, uri } = await sdk.createCollection(collectionData);
// pointer -> canonical c1:b... string
// uri -> ipfs://...

// Attach pointer to the agent (string pointer, not pubkey)
await sdk.setCollectionPointer(asset, pointer!); // lock=true by default

// Parent hierarchy (advanced)
await sdk.setParentAsset(childAsset, parentAsset, { lock: false });
```

Rules enforced on-chain:
- Collection pointer must be `c1:<payload>`, lowercase alphanumeric payload, max 128 bytes.
- `setCollectionPointer`: signer must match immutable `AgentAccount.creator`.
- `setParentAsset`: signer must own child asset and match parent creator snapshot.
- Parent must be a live asset and self-parent is forbidden.
- `lock` defaults to `true` for both methods (`col_locked` / `parent_locked`).

---

## 3. Read Agent Data

```typescript
// Load agent
const agent = await sdk.loadAgent(assetPubkey);
// agent.getOwnerPublicKey(), agent.getAgentWalletPublicKey(), agent.agent_uri, etc.

// Check existence
const exists = await sdk.agentExists(assetPubkey);

// Get owner
const owner = await sdk.getAgentOwner(assetPubkey);

// Check ownership
const isMine = await sdk.isAgentOwner(assetPubkey, myPubkey);

// On-chain metadata
const version = await sdk.getMetadata(assetPubkey, 'version');
```

### Bulk queries (requires premium RPC: Helius, QuickNode, Alchemy)

```typescript
const allAgents = await sdk.getAllAgents();
const withFeedbacks = await sdk.getAllAgents({ includeFeedbacks: true });
const myAgents = await sdk.getAgentsByOwner(ownerPubkey);
```

---

## 4. Update Agent

```typescript
// Update metadata URI
await sdk.setAgentUri(assetPubkey, `ipfs://${newCid}`); // base registry account auto-resolved

// Set on-chain key-value metadata
await sdk.setMetadata(assetPubkey, 'version', '2.0.0');
// First call: ~0.00319 SOL (PDA rent). Updates: ~0.000005 SOL (tx fee only)

// Immutable metadata (permanent, cannot change or delete)
await sdk.setMetadata(assetPubkey, 'certification', 'audited-2026', true);

// Delete metadata (recovers rent)
await sdk.deleteMetadata(assetPubkey, 'version');

// Transfer ownership
await sdk.transferAgent(assetPubkey, newOwnerPubkey); // base registry account auto-resolved

// Sync owner after external NFT transfer
await sdk.syncOwner(assetPubkey);

// Burn agent Core asset (irreversible)
await sdk.burnAgent(assetPubkey);
// Note: burnAgent burns the Core asset; AgentAccount PDA remains until an on-chain unregister exists.
```

---

## 5. Feedback System

### Give feedback

```typescript
// Decimal string auto-encodes: "99.77" -> { value: 9977n, valueDecimals: 2 }
await sdk.giveFeedback(assetPubkey, {
  value: '99.77',
  tag1: Tag.uptime,
  tag2: Tag.day,
  score: 95,                          // 0-100, optional
  endpoint: '/api/v1/generate',       // optional, max 250 bytes
  feedbackUri: `ipfs://${feedbackCid}`,
  feedbackFileHash,                   // optional, 32 bytes Buffer (links file to SEAL)
});
```

### GiveFeedbackParams reference

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `value` | `string \| number \| bigint` | Yes | Metric value. Strings auto-encode decimals ("99.77" -> 9977n, 2) |
| `valueDecimals` | `number` (0-18) | No | Only needed for raw int/bigint. Auto-detected for strings |
| `score` | `number` (0-100) | No | Explicit ATOM score. If omitted, inferred from tag1 |
| `tag1` | `string` | No | Category tag (max 32 UTF-8 bytes) |
| `tag2` | `string` | No | Period/network tag (max 32 UTF-8 bytes) |
| `endpoint` | `string` | No | Endpoint used (max 250 UTF-8 bytes) |
| `feedbackUri` | `string` | No | URI to detailed feedback file (IPFS/HTTPS, max 250 bytes) |
| `feedbackFileHash` | `Buffer` | No | SHA-256 of feedback file content (32 bytes). Binds file to on-chain SEAL |

### Value encoding patterns

```typescript
// Percentage with 2 decimals: 99.75%
const feedbackExamples = [
{ value: '99.75', tag1: Tag.uptime },
// -> encoded: value=9975n, valueDecimals=2

// Milliseconds: 250ms
{ value: 250, tag1: Tag.responseTime, valueDecimals: 0 },

// Currency: $150.25
{ value: '150.25', tag1: Tag.revenues, tag2: Tag.week },

// Negative PnL: -$15.5
{ value: '-15.5', tag1: Tag.tradingYield, tag2: Tag.month },

// Binary check: reachable
{ value: 1, tag1: Tag.reachable, valueDecimals: 0, score: 100 },

// Quality rating (score only)
{ value: '85', tag1: Tag.starred, score: 85 },
];
```

### Score behavior

- `score: 95` -> explicit quality score, used directly by ATOM
- `score: undefined/null` -> ATOM infers from tag1 if it's a known tag (uptime, successRate, starred)
- Tags without auto-score (responseTime, revenues, etc.) require explicit `score` for ATOM impact

ATOM-enabled tags (auto-score from value): `starred`, `uptime`, `successRate`
Context-dependent tags (require explicit score): `reachable`, `ownerVerified`, `responseTime`, `blocktimeFreshness`, `revenues`, `tradingYield`

### Read feedback

```typescript
// Single feedback
const fb = await sdk.readFeedback(assetPubkey, clientPubkey, 0);
// fb.value, fb.valueDecimals, fb.score, fb.tag1, fb.tag2, fb.sealHash

// All feedbacks for agent (indexer-backed)
const all = await sdk.readAllFeedback(assetPubkey);
const withRevoked = await sdk.readAllFeedback(assetPubkey, true);

// Last feedback index for a specific client (NOT a count)
const lastIndex = await sdk.getLastIndex(assetPubkey, clientPubkey);
const nextIndex = lastIndex + 1n; // if no feedback yet: lastIndex = -1n, nextIndex = 0n

// All clients who gave feedback (indexer-backed)
const clients = await sdk.getClients(assetPubkey);

// Via indexer (faster, no premium RPC needed)
const feedbacks = await sdk.getFeedbacksFromIndexer(assetPubkey, { limit: 50 });
const byEndpoint = await sdk.getFeedbacksByEndpoint('/api/generate');
const byTag = await sdk.getFeedbacksByTag('uptime');
```

### Revoke feedback

```typescript
// Requires the sealHash from the original feedback
const fb = await sdk.readFeedback(assetPubkey, clientPubkey, 0);
await sdk.revokeFeedback(assetPubkey, 0, fb.sealHash!);
```

### Respond to feedback (as agent owner)

```typescript
await sdk.appendResponse(
  assetPubkey,
  clientPubkey,
  0,                          // feedbackIndex
  fb.sealHash!,               // sealHash from the feedback
  `ipfs://${responseCid}`,    // response URI
);

// Read responses
const responses = await sdk.readResponses(assetPubkey, clientPubkey, 0);
const count = await sdk.getResponseCount(assetPubkey, clientPubkey, 0);
```

---

## 6. Reputation & ATOM Engine

### Quick reputation summary

```typescript
const summary = await sdk.getSummary(assetPubkey);
// summary.averageScore      -> 0-100
// summary.totalFeedbacks
// summary.positiveCount     -> score >= 50
// summary.negativeCount     -> score < 50

// With filters
const filtered = await sdk.getSummary(assetPubkey, 70);  // minScore=70
const byClient = await sdk.getSummary(assetPubkey, undefined, clientPubkey);
```

### ATOM stats (on-chain reputation engine)

```typescript
const atom = await sdk.getAtomStats(assetPubkey);
if (atom) {
  atom.quality_score;             // 0-10000 (divide by 100 for percentage)
  atom.confidence;                // 0-10000
  atom.ema_score_fast;            // Fast EMA (reacts quickly)
  atom.ema_score_slow;            // Slow EMA (stable baseline)
  atom.ema_volatility;            // Score instability
  atom.diversity_ratio;           // 0-255 (unique caller diversity)
  atom.risk_score;                // 0-100
  atom.trust_tier;                // 0-4

  // Helper methods
  atom.getQualityPercent();       // quality_score / 100
  atom.getConfidencePercent();    // confidence / 100
  atom.getAverageScore();         // ema_score_slow / 100
  atom.estimateUniqueClients();   // HyperLogLog estimation
  atom.getTrustTier();            // TrustTier enum
}
```

### Trust tier

```typescript
const tier = await sdk.getTrustTier(assetPubkey);
// TrustTier.Unrated   = 0
// TrustTier.Bronze    = 1
// TrustTier.Silver    = 2
// TrustTier.Gold      = 3
// TrustTier.Platinum  = 4

const name = trustTierToString(tier); // "Gold"
```

### Enriched summary (ATOM + raw feedback combined)

```typescript
const enriched = await sdk.getEnrichedSummary(assetPubkey);
if (enriched) {
  enriched.trustTier;
  enriched.qualityScore;     // 0-10000
  enriched.confidence;       // 0-10000
  enriched.riskScore;        // 0-100
  enriched.diversityRatio;   // 0-255
  enriched.uniqueCallers;    // HLL estimate
  enriched.emaScoreFast;
  enriched.emaScoreSlow;
  enriched.volatility;
  enriched.totalFeedbacks;
  enriched.averageScore;     // 0-100
  enriched.positiveCount;
  enriched.negativeCount;
}
```

### Reputation from indexer

```typescript
const rep = await sdk.getAgentReputationFromIndexer(assetPubkey);
```

---

## 7. Signing & Verification

### Sign data with agent wallet

```typescript
const signedJson = sdk.sign(assetPubkey, {
  action: 'authorize',
  target: 'task-123',
  timestamp: Date.now(),
});
// Returns: JSON string of SignedPayloadV1
```

### Verify signature

```typescript
// From JSON string
const isValidFromJson = await sdk.verify(signedJson, assetPubkey);

// From IPFS URI
const isValidFromIpfs = await sdk.verify('ipfs://QmPayload...', assetPubkey);

// From HTTPS URL
const isValidFromHttps = await sdk.verify('https://example.com/signed.json', assetPubkey);

// From file path
const isValidFromFile = await sdk.verify('./signed-payload.json', assetPubkey);

// With explicit public key
const isValidWithPubkey = await sdk.verify(signedJson, assetPubkey, walletPubkey);
```

### SignedPayloadV1 format

```typescript
const exampleSignedPayload = {
  v: 1,
  alg: 'ed25519',
  asset: 'base58...',     // agent asset pubkey
  nonce: 'random-base58',
  issuedAt: 1234567890,   // unix seconds
  data: { action: 'authorize', target: 'task-123' }, // your payload
  sig: 'base58...',       // Ed25519 signature
};
```

---

## 8. Liveness Check

```typescript
const defaultReport = await sdk.isItAlive(assetPubkey);
// report.status: 'live' | 'partially' | 'not_live'
// report.okCount, report.totalPinged, report.skippedCount
// report.liveServices[], report.deadServices[], report.skippedServices[]

// With options
const tunedReport = await sdk.isItAlive(assetPubkey, {
  timeoutMs: 10000,
  concurrency: 2,
  treatAuthAsAlive: true,           // 401/403 = alive
  includeTypes: [ServiceType.MCP],  // only check MCP endpoints
});
```

---

## 9. SEAL v1 (Feedback Authenticity)

SEAL provides client-side hash computation matching on-chain Keccak256. Required for `revokeFeedback()` and `appendResponse()`.

```typescript
// Build params (with optional feedbackFileHash)
const fileHash = await SolanaSDK.computeHash(JSON.stringify(feedbackFile));
const params = createSealParams(
  9977n,                        // value (i128)
  2,                            // decimals
  85,                           // score (or null)
  'uptime',                     // tag1
  'day',                        // tag2
  'https://api.example.com',    // endpoint (or null)
  'ipfs://QmFeedback...',       // feedbackUri
  fileHash,                     // feedbackFileHash (or null)
);

// Validate inputs before hashing (throws on invalid params)
validateSealInputs(params);

// Compute hash
const sealHash = computeSealHash(params);  // Buffer, 32 bytes (Keccak256)

// Verify
const valid = verifySealHash({ ...params, sealHash });  // true

// Compute feedback leaf (for hash-chain verification)
const leaf = computeFeedbackLeafV1(
  assetPubkey.toBuffer(),
  clientPubkey.toBuffer(),
  0n,           // feedbackIndex
  sealHash,
  12345n,       // slot
);
```

### Field size limits

| Field | Max bytes | Constant |
|-------|-----------|----------|
| `tag1`, `tag2` | 32 UTF-8 | `MAX_TAG_LEN` |
| `endpoint` | 250 UTF-8 | `MAX_ENDPOINT_LEN` |
| `feedbackUri` | 250 UTF-8 | `MAX_URI_LEN` |
| `feedbackFileHash` | 32 exact | - |

---

## 10. Integrity Verification

### Quick check (O(1))

```typescript
const integrity = await sdk.verifyIntegrity(assetPubkey);
// integrity.valid        -> boolean
// integrity.status       -> 'valid' | 'syncing' | 'corrupted' | 'error'
// integrity.trustworthy  -> boolean
// integrity.totalLag     -> bigint (blocks behind)
// integrity.chains.feedback, .response, .revoke
```

### Deep verification (spot checks)

```typescript
const deep = await sdk.verifyIntegrityDeep(assetPubkey, {
  spotChecks: 10,
  checkBoundaries: true,
  verifyContent: false,  // true = also verify IPFS content hashes (slow)
});
// deep.spotChecksPassed, deep.missingItems, deep.modifiedItems
```

### Full hash-chain replay

```typescript
const full = await sdk.verifyIntegrityFull(assetPubkey, {
  onProgress: (chain, count, total) => {
    console.log(`${chain}: ${count}/${total}`);
  },
});
```

---

## 11. Search & Discovery

### Search agents (via indexer)

```typescript
const results = await sdk.searchAgents({
  owner: 'base58...',
  creator: 'base58...',
  collection: 'base58...',              // base registry collection pubkey
  collectionPointer: 'c1:bafybeigdyr...',
  parentAsset: 'base58...',
  wallet: 'base58...',
  colLocked: true,
  limit: 20,
  offset: 0,
});
```

### Leaderboard

```typescript
const top = await sdk.getLeaderboard({
  minTier: 2,        // Silver+
  limit: 50,
  collection: 'base58...',
});
```

### Global stats

```typescript
const global = await sdk.getGlobalStats();
// global.total_agents, total_feedbacks, platinum_agents, gold_agents, avg_quality
```

### Find agent by wallet

```typescript
const agent = await sdk.getAgentByWallet(walletPubkey.toBase58());
```

### Endpoint crawler

```typescript
const crawler = new EndpointCrawler(5000);
const mcp = await crawler.fetchMcpCapabilities('https://agent.com/mcp');
// mcp.mcpTools, mcp.mcpPrompts, mcp.mcpResources

const a2a = await crawler.fetchA2aCapabilities('https://agent.com');
// a2a.a2aSkills
```

---

## 12. SDK Introspection

```typescript
// Chain identity (CAIP-2 format)
const chain = await sdk.chainId();       // 'solana-devnet'
const cluster = sdk.getCluster();         // 'devnet' | 'testnet' | 'mainnet-beta' | 'localnet'

// Program IDs
const programs = sdk.getProgramIds();
// programs.identityRegistry   -> PublicKey
// programs.reputationRegistry -> PublicKey
// programs.agentRegistry      -> PublicKey
// programs.atomEngine         -> PublicKey

// Registry addresses as strings (parity with agent0-ts)
const regs = sdk.registries();
// { IDENTITY: 'base58...', REPUTATION: 'base58...', ...legacy aliases }

// RPC info
const rpcUrl = sdk.getRpcUrl();
const isDefaultRpc = sdk.isUsingDefaultDevnetRpc();
const canBulkQuery = sdk.supportsAdvancedQueries();
const readOnly = sdk.isReadOnly;

// Base collection (single-collection architecture)
const base = await sdk.getBaseCollection();

// Advanced: access underlying clients
const solanaClient = sdk.getSolanaClient();
const feedbackMgr = sdk.getFeedbackManager();
```

---

## 13. Tags Reference

### Category tags (tag1)

| Constant | String | Value Type | ATOM Auto-Score |
|----------|--------|-----------|-----------------|
| `Tag.starred` | `'starred'` | 0-100 | Yes |
| `Tag.uptime` | `'uptime'` | percentage | Yes |
| `Tag.successRate` | `'successRate'` | percentage | Yes |
| `Tag.reachable` | `'reachable'` | 0 or 1 | No |
| `Tag.ownerVerified` | `'ownerVerified'` | 0 or 1 | No |
| `Tag.responseTime` | `'responseTime'` | ms | No |
| `Tag.blocktimeFreshness` | `'blocktimeFreshness'` | blocks | No |
| `Tag.revenues` | `'revenues'` | currency | No |
| `Tag.tradingYield` | `'tradingYield'` | percentage | No |

### Period tags (tag2)

| Constant | String |
|----------|--------|
| `Tag.day` | `'day'` |
| `Tag.week` | `'week'` |
| `Tag.month` | `'month'` |
| `Tag.year` | `'year'` |

### x402 tags (tag1) - Client -> Agent

| Constant | String |
|----------|--------|
| `Tag.x402ResourceDelivered` | `'x402-resource-delivered'` |
| `Tag.x402DeliveryFailed` | `'x402-delivery-failed'` |
| `Tag.x402DeliveryTimeout` | `'x402-delivery-timeout'` |
| `Tag.x402QualityIssue` | `'x402-quality-issue'` |

### x402 tags (tag1) - Agent -> Client

| Constant | String |
|----------|--------|
| `Tag.x402GoodPayer` | `'x402-good-payer'` |
| `Tag.x402PaymentFailed` | `'x402-payment-failed'` |
| `Tag.x402InsufficientFunds` | `'x402-insufficient-funds'` |
| `Tag.x402InvalidSignature` | `'x402-invalid-signature'` |

### x402 network tags (tag2)

| Constant | String |
|----------|--------|
| `Tag.x402Evm` | `'exact-evm'` |
| `Tag.x402Svm` | `'exact-svm'` |

### Tag utilities

```typescript
isKnownTag('uptime');              // true
isKnownTag('custom-metric');       // false
getTagDescription('successRate');   // 'Task completion success percentage'
```

Custom tags are fully supported - any string up to 32 UTF-8 bytes.

---

## 14. OASF Taxonomy

```typescript
// List taxonomy slugs
const skills = getAllSkills();   // 136 skills
const domains = getAllDomains(); // 204 domains
```

---

## 15. Hash Utilities

```typescript
// SHA-256 (async, browser-compatible via WebCrypto)
const hash = await SolanaSDK.computeHash('My feedback content');
const bufHash = await SolanaSDK.computeHash(Buffer.from(jsonData));
// Returns: Buffer (32 bytes)

// URI hash (zeros for IPFS/Arweave since CID is already content-addressable)
const uriHash = await SolanaSDK.computeUriHash('https://example.com/data.json');
// -> SHA-256 of the URI string
const ipfsHash = await SolanaSDK.computeUriHash('ipfs://Qm...');
// -> Buffer.alloc(32) (zeros)

// Keccak-256 (synchronous, used by SEAL v1)
import { keccak256 } from '8004-solana';
const k = keccak256(Buffer.from('data'));

// SHA-256 sync (CJS context only — uses require('crypto'), throws in pure ESM or browser)
import { sha256Sync } from '8004-solana';
const s = sha256Sync('data');  // Uint8Array (32 bytes)
```

---

## 16. Value Encoding

```typescript
import {
  encodeReputationValue,
  decodeToDecimalString,
  decodeToNumber,
} from '8004-solana';

// Encode: decimal string -> { value: bigint, valueDecimals: number }
const encoded = encodeReputationValue('99.77');
// { value: 9977n, valueDecimals: 2, normalized: '99.77' }

const neg = encodeReputationValue('-15.5');
// { value: -155n, valueDecimals: 1, normalized: '-15.5' }

const raw = encodeReputationValue(9977n, 2);
// { value: 9977n, valueDecimals: 2, normalized: '99.77' }

// Decode: bigint + decimals -> string or number
decodeToDecimalString(9977n, 2);   // '99.77'
decodeToDecimalString(-155n, 1);   // '-15.5'
decodeToNumber(9977n, 2);          // 99.77

// Limits: max 18 decimal places, clamped to i128 range
```

---

## 17. Canonical JSON & Signing Utilities

```typescript
import {
  canonicalizeJson,
  normalizeSignData,
  createNonce,
} from '8004-solana';

// RFC 8785 canonical JSON (deterministic key ordering, no whitespace)
canonicalizeJson({ b: 2, a: 1 });  // '{"a":1,"b":2}'

// Normalize data for signing (handles BigInt, PublicKey, Date, Buffer)
const normalized = normalizeSignData({
  amount: 100n,           // -> { $bigint: '100' }
  key: somePubkey,        // -> { $pubkey: 'base58...' }
  when: new Date(),       // -> { $date: 'ISO...' }
  data: Buffer.from([1]), // -> { $bytes: 'AQ==', encoding: 'base64' }
});

// Cryptographic nonce generation (base58-encoded random bytes)
const nonce = createNonce();     // 16 bytes default
const nonce32 = createNonce(32); // 32 bytes
```

---

## 18. IPFS Operations

```typescript
// Add data
const jsonCid = await ipfs.addJson({ key: 'value' });
const rawCid = await ipfs.add('raw string data');
const fileCid = await ipfs.addFile('./image.png');

// Add registration file (normalizes and formats)
const registrationCid = await ipfs.addRegistrationFile(registrationFile);

// Retrieve
const data = await ipfs.get(jsonCid);              // raw string
const json = await ipfs.getJson(jsonCid);          // parsed JSON
const reg = await ipfs.getRegistrationFile(registrationCid); // RegistrationFile

// Supports ipfs:// prefix
const ipfsPrefixedData = await ipfs.get('ipfs://QmAbc...');

// Pin/unpin
await ipfs.pin(fileCid);
await ipfs.unpin(fileCid);

// Cleanup
await ipfs.close();
```

---

## 19. Server Mode (skipSend)

For browser wallets or external signing:

```typescript
// Get unsigned transaction
const assetKeypair = Keypair.generate();
const prepared = await sdk.registerAgent(uri, {
  skipSend: true,
  signer: ownerPubkey,              // required when SDK has no signer
  assetPubkey: assetKeypair.publicKey, // required in skipSend mode
});
// prepared.transaction -> base64 serialized unsigned transaction
// prepared.signer -> base58 of the required signer

// For agent wallet (browser wallet flow)
const { message, complete } = await sdk.prepareSetAgentWallet(
  assetPubkey,
  walletPubkey,
  { signer: ownerPubkey } // optional if SDK was initialized with signer
);
const signature = await phantomWallet.signMessage(message);
await complete(signature);
```

All write methods accept `{ skipSend: true }` in their options.

---

## 20. Indexer Client (Direct Access)

```typescript
const indexer = sdk.getIndexerClient();

// Check availability
const available = await sdk.isIndexerAvailable();

// Direct queries
const agents = await indexer.getAgentsByOwner('base58...');
const feedbacks = await indexer.getFeedbacks('base58...', { limit: 100 });
const leaderboard = await indexer.getLeaderboard({ minTier: 3 });
```

### Wait for indexer sync after write

```typescript
await sdk.giveFeedback(assetPubkey, feedbackParams);

// Poll until indexer catches up (returns true if synced, false on timeout)
const synced = await sdk.waitForIndexerSync(
  async () => {
    const fbs = await sdk.getFeedbacksFromIndexer(assetPubkey);
    return fbs.length >= expectedCount;
  },
  { timeout: 30000 }  // ms, default 30s
);
```

---

## 21. Error Handling

```typescript
import {
  IndexerError,
  IndexerUnavailableError,
  IndexerTimeoutError,
  IndexerRateLimitError,
  UnsupportedRpcError,
  RpcNetworkError,
} from '8004-solana';

try {
  const agents = await sdk.getAllAgents();
} catch (e) {
  if (e instanceof UnsupportedRpcError) {
    // Default RPC doesn't support getProgramAccounts
    // Use Helius, QuickNode, or Alchemy
  }
  if (e instanceof IndexerUnavailableError) {
    // Indexer is down, SDK falls back to RPC if indexerFallback=true
  }
  if (e instanceof IndexerRateLimitError) {
    // Back off and retry
  }
}
```

### Methods requiring premium RPC

`getAllAgents()`, `getAgentsByOwner()`, `getCollectionAgents()`, `getCollections()`

Indexer-backed reads (`readAllFeedback()`, `getClients()`, `getLastIndex()`, `readResponses()`) do not require premium RPC, but they do require a reachable indexer.

---

## 22. Operation Costs (Solana devnet)

| Operation | Cost | Notes |
|-----------|------|-------|
| `registerAgent()` | ~0.00651 SOL | Base registration (without ATOM init) |
| `registerAgent(..., { atomEnabled: true })` | higher than base | Includes ATOM stats initialization in the same transaction |
| `giveFeedback()` (1st for agent) | ~0.00332 SOL | Creates reputation PDA |
| `giveFeedback()` (subsequent) | ~0.00209 SOL | Feedback PDA only |
| `setMetadata()` (1st key) | ~0.00319 SOL | PDA rent |
| `setMetadata()` (update) | ~0.000005 SOL | TX fee only |
| `appendResponse()` (1st) | ~0.00275 SOL | Response + index PDAs |
| `appendResponse()` (subsequent) | ~0.00163 SOL | Response PDA only |
| `revokeFeedback()` | ~0.000005 SOL | TX fee only |
| `deleteMetadata()` | recovers rent | Returns lamports to owner |

---

## 23. Common Patterns

### Monitor agent health

```typescript
const report = await sdk.isItAlive(assetPubkey);
if (report.status !== 'live') {
  await sdk.giveFeedback(assetPubkey, {
    value: 0,
    valueDecimals: 0,
    tag1: Tag.reachable,
    score: 0,
    feedbackUri: `ipfs://${alertCid}`,
  });
}
```

### Periodic uptime reporting

```typescript
const uptimePercent = calculateUptime(); // your logic
await sdk.giveFeedback(assetPubkey, {
  value: uptimePercent.toFixed(2),  // "99.75" auto-encodes
  tag1: Tag.uptime,
  tag2: Tag.day,
  feedbackUri: `ipfs://${reportCid}`,
});
```

### Trust-gated interaction

```typescript
const tier = await sdk.getTrustTier(assetPubkey);
if (tier < TrustTier.Silver) {
  throw new Error('Agent trust too low for this operation');
}
```

### x402 payment feedback (full flow)

```typescript
// 1. Build the feedback file JSON (off-chain proof of payment)
const feedbackFile = {
  version: '1.0',
  type: 'x402-feedback',
  agent: assetPubkey.toBase58(),
  client: clientPubkey.toBase58(),
  endpoint: '/api/generate',
  timestamp: new Date().toISOString(),
  proofOfPayment: {
    txHash: 'base58-tx-signature...',
    fromAddress: clientPubkey.toBase58(),
    toAddress: agentWalletPubkey.toBase58(),
    amount: '0.001',
    token: 'SOL',
    chainId: await sdk.chainId(),   // 'solana-devnet'
  },
  settlement: {
    success: true,
    network: 'solana',
    settledAt: new Date().toISOString(),
  },
  result: {
    delivered: true,
    latencyMs: 230,
    quality: 'good',
  },
};

// 2. Upload to IPFS
const feedbackCid = await ipfs.addJson(feedbackFile);

// 3. Optionally compute content hash for SEAL integrity
const feedbackFileHash = await SolanaSDK.computeHash(
  JSON.stringify(feedbackFile)
);

// 4. Submit on-chain feedback with proof link
await sdk.giveFeedback(assetPubkey, {
  value: '100.00',
  tag1: Tag.x402ResourceDelivered,
  tag2: Tag.x402Svm,
  score: 95,
  endpoint: '/api/generate',
  feedbackUri: `ipfs://${feedbackCid}`,
  feedbackFileHash,  // links file content to on-chain SEAL
});

// Agent-side: report good payer
await sdk.giveFeedback(clientAgentPubkey, {
  value: '1',
  valueDecimals: 0,
  tag1: Tag.x402GoodPayer,
  tag2: Tag.x402Svm,
  score: 100,
  feedbackUri: `ipfs://${payerProofCid}`,
});
```

### Verify before trusting indexer data

```typescript
const integrity = await sdk.verifyIntegrity(assetPubkey);
if (!integrity.trustworthy) {
  console.warn(`Indexer data not trustworthy: ${integrity.status}`);
  // Fall back to on-chain queries
}
```

---

## 24. Program IDs

```typescript
import {
  PROGRAM_ID,                       // devnet default Agent Registry
  ATOM_ENGINE_PROGRAM_ID,           // devnet default ATOM
  DEVNET_AGENT_REGISTRY_PROGRAM_ID,
  DEVNET_ATOM_ENGINE_PROGRAM_ID,
  MAINNET_AGENT_REGISTRY_PROGRAM_ID,
  MAINNET_ATOM_ENGINE_PROGRAM_ID,
  MPL_CORE_PROGRAM_ID,
} from '8004-solana';
```

Cluster mapping in SDK defaults:
- `devnet` / `testnet` / `localnet`: devnet program defaults unless overridden.
- `mainnet-beta`: mainnet program defaults.

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

8004-solana-sdk

Directory Structure

SKILL.md

Report

Notice