|
| 1 | +# ADAMANT JS API: AI Agent Operating Manual |
| 2 | + |
| 3 | +This document defines how AI agents should work in this repository. |
| 4 | + |
| 5 | +## Mission |
| 6 | + |
| 7 | +`adamant-api-jsclient` is a TypeScript/Node.js API library for the ADAMANT blockchain. |
| 8 | + |
| 9 | +Agent output must optimize for: |
| 10 | + |
| 11 | +1. Security and cryptographic correctness |
| 12 | +2. Reliability of node access, retries, and failover |
| 13 | +3. Backward compatibility of the public API and transaction behavior |
| 14 | +4. Open-source maintainability and contributor clarity |
| 15 | + |
| 16 | +If tradeoffs are required, preserve secret safety, signing correctness, and network compatibility first. |
| 17 | + |
| 18 | +## Architecture Direction |
| 19 | + |
| 20 | +- Evolve this repository toward a unified, modular JavaScript SDK for the ADAMANT blockchain and ADM-derived external cryptocurrency wallets |
| 21 | +- Keep the current external coin scope focused on authoritative metadata from `adamant-wallets`, deterministic key and address derivation, and address validation; external-chain balances, transaction history, signing, and broadcasting require separate explicit tasks |
| 22 | +- Keep coin-specific dependencies inside `adamant-api` for now, but isolate coin implementations behind subpath exports and do not import them from the root entry point so ADM-only consumers do not load or bundle Bitcoin, Ethereum, or other coin code |
| 23 | +- Preserve the existing root API while introducing stable module boundaries and subpath exports; splitting coin implementations into separately installed packages is not part of the current architecture task |
| 24 | +- Leave room for future agent-oriented workflows and a signer abstraction without implementing or exposing those APIs prematurely; current architectural changes should avoid choices that would require breaking the SDK to add them later |
| 25 | +- Treat `@adamant/sdk` as a prospective package identity, not an alias or approved rename. The repository remains `adamant-api-jsclient`, and package naming changes require a separate compatibility and migration plan |
| 26 | +- `adamant-wallets-js` is archived and is not an implementation source; retain its history only as prior research |
| 27 | + |
| 28 | +See [Refactor] Evolve adamant-api-jsclient into a modular ADM and coin SDK <https://github.com/Adamant-im/adamant-api-jsclient/issues/77> for details. |
| 29 | + |
| 30 | +## Language Policy |
| 31 | + |
| 32 | +- Developers may communicate with AI in any language |
| 33 | +- All repository artifacts must be in English only |
| 34 | +- Write code, comments, docs, commit messages, issue text, and PR text in English |
| 35 | + |
| 36 | +## Sources of Truth |
| 37 | + |
| 38 | +Use these sources when implementing or reviewing changes: |
| 39 | + |
| 40 | +- This repository: `README.md`, `package.json`, `CONTRIBUTING.md`, current code, and passing tests |
| 41 | +- ADAMANT docs: <https://docs.adamant.im> |
| 42 | +- ADAMANT schema source for generated API types: <https://github.com/Adamant-im/adamant-schema> |
| 43 | +- Related wallet metadata and OpenAPI spec: <https://github.com/Adamant-im/adamant-wallets> and <https://github.com/Adamant-im/adamant-wallets/blob/dev/specification/openapi.json> |
| 44 | +- Org-wide issue and label governance: <https://github.com/Adamant-im/.github> |
| 45 | + |
| 46 | +Important repository-specific rule: |
| 47 | + |
| 48 | +- If docs and code disagree, treat current code and passing tests as implementation truth and document the drift |
| 49 | +- `adamant-wallets` is a related source for wallet-facing coin and token metadata, address regexes, node and service health-check settings, explorer links, and blockchain definitions; it is especially relevant when changing `src/coins/*`, external wallet integrations, or future wallet-oriented API contracts |
| 50 | + |
| 51 | +## Issue, Label, and PR Conventions |
| 52 | + |
| 53 | +When creating issues: |
| 54 | + |
| 55 | +1. Search existing issues first: <https://github.com/Adamant-im/adamant-api-jsclient/issues> |
| 56 | +2. Use a concise prefixed title |
| 57 | +3. Apply labels from `Adamant-im/.github/labels.json` |
| 58 | +4. Link related issues and PRs explicitly |
| 59 | + |
| 60 | +Recommended issue title prefixes: |
| 61 | + |
| 62 | +- `[Bug]` |
| 63 | +- `[Feat]` |
| 64 | +- `[Enhancement]` |
| 65 | +- `[Refactor]` |
| 66 | +- `[Docs]` |
| 67 | +- `[Test]` |
| 68 | +- `[Chore]` |
| 69 | +- `[Task]` |
| 70 | + |
| 71 | +Label policy: |
| 72 | + |
| 73 | +- Use a small but informative set |
| 74 | +- Prefer one type label and one or more domain labels such as `APIs`, `NodeJS`, `TypeScript`, `Security`, `Privacy`, or `Nodes` |
| 75 | +- Keep label casing aligned with org rules |
| 76 | + |
| 77 | +PR and branch policy: |
| 78 | + |
| 79 | +- Target `dev`, not `master` |
| 80 | +- Keep PR titles in `Type: Short summary` form such as `Docs: Add AGENTS.md` |
| 81 | +- Do not use issue-style square-bracket prefixes in PR titles |
| 82 | +- Keep commits compatible with Conventional Commits and current commitlint rules |
| 83 | + |
| 84 | +## System Map |
| 85 | + |
| 86 | +Key areas of this repository: |
| 87 | + |
| 88 | +- `src/index.ts`: public exports |
| 89 | +- `src/api/index.ts`: `AdamantApi` HTTP client, retries, request helpers, endpoint surface |
| 90 | +- `src/api/generated.ts`: generated API DTO types copied from `adamant-schema` |
| 91 | +- `src/helpers/healthCheck.ts`: node health checks, sync grouping, active-node selection, socket coordination |
| 92 | +- `src/helpers/keys.ts`: passphrase hashing, ADM keypair derivation, ADM address creation |
| 93 | +- `src/helpers/encryptor.ts`: message encryption and decryption |
| 94 | +- `src/helpers/transactions/*`: transaction creation, hashing, signing, and IDs |
| 95 | +- `src/helpers/wsClient.ts`: Socket.IO subscriptions for incoming transactions |
| 96 | +- `src/coins/*.ts`: BTC, ETH, DASH, and DOGE wallet helpers |
| 97 | + |
| 98 | +## Non-Negotiable Security Rules |
| 99 | + |
| 100 | +- Never log passphrases, mnemonic seeds, private keys, decrypted payloads, or sensitive tokens |
| 101 | +- Never weaken key derivation, encryption, signature generation, or transaction hashing behavior |
| 102 | +- Never change transaction byte layout, IDs, or signature semantics without explicit coordinated protocol work |
| 103 | +- Validate external inputs before using them in network requests, signing, or wallet generation |
| 104 | +- Minimize new dependencies, especially cryptography and networking dependencies |
| 105 | +- Do not hand-edit `src/api/generated.ts` for routine changes when regeneration from schema is the correct path |
| 106 | + |
| 107 | +## Reliability and Decentralization Rules |
| 108 | + |
| 109 | +- Do not hardcode a single node as the only viable path |
| 110 | +- Preserve health-check behavior, retry logic, and active-node switching unless the task explicitly changes them |
| 111 | +- Keep node selection compatible with height-based sync checks and socket support filtering |
| 112 | +- Fail safely on malformed data, timeouts, and partial node outages |
| 113 | +- Prefer clear returned errors and logs over silent failure |
| 114 | + |
| 115 | +## Testing and Validation |
| 116 | + |
| 117 | +For code changes, baseline validation is: |
| 118 | + |
| 119 | +- `npm run compile` |
| 120 | +- `npm test` |
| 121 | +- `npm run lint` |
| 122 | + |
| 123 | +Additional repository-specific expectations: |
| 124 | + |
| 125 | +- Add or update tests near the changed behavior in collocated `tests` directories |
| 126 | +- If you change generated API types, regenerate from `adamant-schema`, then run compile and tests |
| 127 | +- For docs-only changes, say explicitly that runtime tests were not run |
| 128 | + |
| 129 | +## Working Style |
| 130 | + |
| 131 | +- Prefer focused patches over broad rewrites |
| 132 | +- Match local file style unless there is a strong reason to change it |
| 133 | +- Preserve public exports and backward-compatible behavior where possible |
| 134 | +- Update docs when behavior or workflow changes |
| 135 | +- When a CLI tool accepts multi-line input, prefer a temporary file in `.ai-ignored/` |
| 136 | + |
| 137 | +## Done Criteria |
| 138 | + |
| 139 | +A change is not complete until all of the following are true: |
| 140 | + |
| 141 | +1. Security-sensitive behavior is preserved or intentionally documented |
| 142 | +2. Relevant validation commands were run or an explicit blocker was reported |
| 143 | +3. Documentation was updated when behavior or workflow changed |
| 144 | +4. No secret exposure or single-point-of-failure regression was introduced |
0 commit comments