mixin_bot 1.4.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 73565cefb791be042d4130d44248e575b30cac2b00d032508e6d2a215d02c845
-  data.tar.gz: 521142f48775c4eb1166c4ccb22fe974bf91adab0c3a1b900980660b440d9606
+  metadata.gz: 5d03bd8cb9d6710487b3ef3c5ed57e88136a0bcb99c841d366fe7e24b3e8a43c
+  data.tar.gz: 5e0c70f36c6ca291a0e65e11137434474ad804829e67c553a7b8fbee651b5ea9
 SHA512:
-  metadata.gz: c5d2729f574eca707316ea7bc05989a5f4fe411c562a81bdbf88a46b2dec855cf9f4701c33ce17016ac034ef490c42a01bddc3f9d7f3e819254fc228dc0b7b09
-  data.tar.gz: 9a45a5441a0859dc404011788a5fac8afced8f7c1d0e9db100fe404abe05258f7364539b1417f6360367a65e861340b9b16223c7d63bb65d1e831877f0997f35
+  metadata.gz: a717d7b6103c5e1df8b1cb044303114c159cbc31cb47e6f0a33e9c7e7906a204c0fd3ab92507b9eb903979c603c5031e192a2f6bf392ee4d2636eea5f3f3c88c
+  data.tar.gz: 75a350a5053a490aff9cfac0b556e70dad2d2e20bf4cafb4408640b6d5c5dd932ec2264bf2cf952a3dec511b4e71855d4c5996e7acb32ccf6ea201b17943c80f

data/AGENTS.md

@@ -0,0 +1,75 @@
+# AGENTS.md — MixinBot
+
+Ruby gem (v2.0.0): Mixin Network REST SDK + `mixinbot` CLI. Parity target: [bot-api-go-client](https://github.com/MixinNetwork/bot-api-go-client).
+
+## Commands
+
+```bash
+bundle install
+rake                    # default: test + rubocop (in that order)
+rake test               # offline suite only
+rake test_live          # LIVE=1 rake test (requires test/config.yml)
+rake mixin_bot:api_coverage  # check API_COVERAGE.md has no missing entries
+rake build              # build .gem
+rake rdoc               # generate doc/
+```
+
+**Single test**: `ruby -Itest -Ilib test/mixin_bot/some_test.rb`
+
+## Repository layout
+
+```
+lib/mixin_bot/
+  api.rb + api/*.rb     # One module per API domain (Transfer, Message, Blaze, …)
+  client.rb             # Faraday HTTP client → ApiEnvelope
+  cli.rb + cli/*.rb     # mixinbot CLI (Thor)
+  configuration.rb      # Credentials and hosts
+  transaction/          # Raw transaction encode/decode
+  utils.rb              # Crypto and encoding helpers
+lib/mvm/                # MVM helpers (excluded from default rake test)
+bin/mixinbot            # CLI entrypoint
+test/                   # Minitest + WebMock (offline by default)
+docs/agent/             # LLM-oriented CLI and cookbook docs
+```
+
+## CI and release
+
+- **CI** (`.github/workflows/ci.yml`): `pull_request` and `push` to `main` — `rake test` on Ruby 3.2/3.3/4.0, `rake rubocop` (3.3), `rake mixin_bot:api_coverage`.
+- **Release** (`.github/workflows/release.yml`): push tag `v*` (must match `MixinBot::VERSION`, e.g. tag `v2.0.0` for `VERSION = '2.0.0'`) → `rake build` → RubyGems via [trusted publishing](https://guides.rubygems.org/trusted-publishing/) (OIDC; workflow `release.yml`, no repo secret).
+- **Dependabot** (`.github/dependabot.yml`): weekly Bundler and GitHub Actions updates; Dependabot PRs use the same CI workflow.
+
+## Conventions
+
+- **Ruby** >= 3.2 (CI: 3.2, 3.3, 4.0)
+- **HTTP responses**: `MixinBot::Models::ApiEnvelope` — use `res['data']` or delegated keys
+- **Safe transfers**: require `spend_key`; prefer `create_safe_transfer` / `create_transfer` (Safe pipeline)
+- **Legacy APIs**: `create_legacy_transfer`, `POST /transfers` — deprecated, warns once
+- **Tests**: offline WebMock stubs by default; `LIVE=1 rake test` for integration
+- **MVM tests**: excluded from `rake test`; run separately if needed
+- **Lint**: RuboCop via `rake` (runs after tests in default task)
+
+## CLI boundaries
+
+Interactive API methods are **excluded** from `mixinbot call` (defined in `CLIHelpers::INTERACTIVE_API_METHODS` at `lib/mixin_bot/cli/base.rb:28`):
+- `start_blaze_connect`, `blaze`, `upload_attachment`
+
+Use the Ruby API + EventMachine for Blaze (see `examples/blaze.rb`).
+
+Agent-friendly CLI features:
+- `mixinbot schema -o json` — machine-readable command schema
+- `--output json|yaml|pretty` — structured stdout; auto JSON when piped
+- `mixinbot list --limit N --offset N -o json` — bounded method registry
+
+See [docs/agent/cli.md](docs/agent/cli.md).
+
+## Error types
+
+Custom errors in `lib/mixin_bot/errors.rb`: `ResponseError`, `UnauthorizedError`, `InsufficientBalanceError`, `UtxoInsufficientError`, `PinError`, `NotFoundError`, etc.
+
+CLI maps these to structured error kinds (`auth`, `api_error`, `not_found`, …) when `--output json`.
+
+## What not to do
+
+- Do not commit secrets (`test/config.yml`, keystore files with real keys)
+- Do not use legacy transfer APIs in new code
+- Do not expect Blaze WebSocket flows to work via CLI

data/API_COVERAGE.md

@@ -0,0 +1,143 @@
+# Mixin Go SDK API Coverage
+
+Reference: [bot-api-go-client](https://github.com/MixinNetwork/bot-api-go-client) (`package bot`).
+
+Status values: `done` | `alias` | `n/a` (CLI-only / config)
+
+| Go symbol | Ruby method | HTTP / notes | Status |
+|-----------|-------------|--------------|--------|
+| **Auth** |
+| SignAuthenticationToken | `API#access_token` | JWT | done |
+| SignAuthenticationTokenWithoutBody | `API#access_token` | JWT | alias |
+| SignAuthenticationTokenWithRequestID | `API#access_token` | JWT | alias |
+| SignOauthAccessToken | `API#sign_oauth_access_token` | JWT | done |
+| OAuthGetAccessToken | `API#oauth_token` | POST `/oauth/token` | done |
+| **Users** |
+| CreateUserSimple | `API#create_user` | POST `/users` | done |
+| CreateUser | `API#create_user` | POST `/users` | done |
+| GetUser | `API#user` | GET `/users/:id` | done |
+| GetUsers | `API#fetch_users` | POST `/users/fetch` | done |
+| SearchUser | `API#search_user` | GET `/search/:q` | done |
+| UpdateTipPin | `API#update_tip_pin` | POST `/pin/update` | done |
+| UpdatePin | `API#update_pin` | POST `/pin/update` | done |
+| UserMe / RequestUserMe | `API#me` / `API#safe_me` | GET `/me`, `/safe/me` | done |
+| UpdateUserMe | `API#update_me` | POST `/me` | done |
+| UpdatePreference | `API#update_preferences` | POST `/me/preferences` | done |
+| Relationship | `API#relationship` | POST `/relationships` | done |
+| GenerateUserChecksum | `MixinBot.utils.generate_user_checksum` | local | done |
+| RegisterSafe* | `API#safe_register`, `#migrate_to_safe` | POST `/safe/users` | done |
+| UpgradeLegacyUser | `API#upgrade_legacy_user` | POST `/legacy/users` | done |
+| FetchUserSession | `API#fetch_user_sessions` | POST `/sessions/fetch` | done |
+| **Sessions / PIN** |
+| EncryptEd25519PIN | `API#encrypt_pin` | local | done |
+| VerifyPIN | `API#verify_pin` | POST `/pin/verify` | done |
+| VerifyPINTip | `API#verify_pin_tip` | POST `/pin/verify` | alias |
+| **Assets** |
+| ListAssetWithBalance | `API#assets` | GET `/assets` | done |
+| FetchAssets | `API#fetch_assets` | POST `/safe/assets/fetch` | done |
+| ReadAssetFee | `API#asset_fee` | GET `/safe/assets/:id/fees` | done |
+| AssetBalance* | `API#asset_balance` | derived from outputs | done |
+| UserAssetBalance | `API#user_asset_balance` | GET `/safe/outputs` | done |
+| ReadAsset | `API#network_asset` | GET `/network/assets/:id` | done |
+| ReadAssetTicker* | `API#network_ticker` | GET `/network/ticker` | done |
+| AssetSearch | `API#network_asset_search` | GET `/network/assets/search/:q` | done |
+| ReadNetworkAssets | `API#network_assets` | GET `/network` | done |
+| ReadNetworkAssetsTop | `API#network_assets_top` | GET `/network/assets/top` | done |
+| GetFiats / Fiats | `API#fiats` | GET `/external/fiats` | done |
+| **Chains** |
+| ReadNetworkChainById | `API#network_chain` | GET `/network/chains/:id` | done |
+| ReadNetworkChains | `API#network_chains` | GET `/network/chains` | done |
+| GetChainName | `API#chain_name` | local | done |
+| IsChainId | `API#chain_id?` | local | done |
+| GetFullChains | `API#full_chains` | local | done |
+| **Outputs / deposits** |
+| ListOutputs / ListUnspentOutputs | `API#safe_outputs` | GET `/safe/outputs` | done |
+| GetOutput | `API#safe_output` | GET `/safe/outputs/:id` | done |
+| FetchPendingSafeDeposits | `API#pending_safe_deposits` | GET `/safe/deposits` | done |
+| CreateDepositEntry | `API#safe_deposit_entries` | POST `/safe/deposit/entries` | done |
+| **Transactions (Safe)** |
+| SendTransaction* | `API#create_safe_transfer` | pipeline | done |
+| GetTransactionById* | `API#safe_transaction` | GET `/safe/transactions/:id` | done |
+| VerifyRawTransaction | `API#verify_raw_transaction` | POST `/safe/transaction/requests` | done |
+| SendRawTransaction | `API#send_safe_transaction` | POST `/safe/transactions` | done |
+| BuildRawTransaction | `API#build_safe_transaction` | local | done |
+| RequestGhostRecipientsWithTraceId | `API#request_ghost_recipients_with_trace_id` | POST `/safe/keys` | done |
+| RequestSafeGhostKeys | `API#create_safe_keys` | POST `/safe/keys` | done |
+| CreateMultisigRawTx | `API#create_multisig_raw_tx` | local + keys | done |
+| CreateObjectStorageTransaction | `API#create_object_storage_transaction` | pipeline | done |
+| EstimateStorageCost | `API#estimate_storage_cost` | local | done |
+| StorageRecipient | `API#storage_recipient` | local | done |
+| SendKernelTransactionFromAccount | `API#send_kernel_transaction_from_account` | documented N/I | done |
+| **Multisig** |
+| CreateSafeMultisigRequest | `API#create_safe_multisig_request` | POST `/safe/multisigs` | done |
+| FetchSafeMultisigRequest | `API#safe_multisig_request` | GET `/safe/multisigs/:id` | done |
+| ReadMultisigs* | `API#read_multisigs` / `#legacy_outputs` | GET `/multisigs/outputs` | done |
+| CreateMultisig / Sign / Unlock / Cancel | `API#create_*_multisig_*` | legacy paths | done |
+| **Snapshots** |
+| SafeSnapshots* | `API#safe_snapshots` | GET `/safe/snapshots` | done |
+| SafeSnapshotById | `API#safe_snapshot` | GET `/safe/snapshots/:id` | done |
+| SafeNotifySnapshot | `API#create_safe_snapshot_notification` | POST notifications | done |
+| Snapshots / SnapshotById / SnapshotByTraceId | `API#snapshots`, `#snapshot`, `#snapshot_by_trace_id` | legacy | done |
+| NetworkSnapshot* | `API#network_snapshot(s)` | legacy | done |
+| **Withdrawals / addresses** |
+| CreateAddress / ReadAddress / DeleteAddress | `API#create_withdraw_address`, etc. | `/addresses` | done |
+| GetAddressesByAssetId | `API#withdraw_addresses` | GET `/assets/:id/addresses` | done |
+| CheckAddress | `API#check_address` | GET `/external/addresses/check` | done |
+| SendWithdrawal | `API#withdrawals` | POST `/withdrawals` | done |
+| **Conversations / messages** |
+| CreateContactConversation | `API#create_contact_conversation` | POST `/conversations` | done |
+| CreateGroupConversation | `API#create_group_conversation` | POST `/conversations` | done |
+| ConversationShow | `API#conversation` | GET `/conversations/:id` | done |
+| JoinConversation | `API#join_conversation` | POST `.../join` | done |
+| RotateConversation | `API#rotate_conversation` | POST `.../rotate` | done |
+| UpdateParticipants | `API#add/remove/..._participants` | POST participants | done |
+| PostMessage(s) | `API#send_message` | POST `/messages` | done |
+| EncryptMessageData / DecryptMessageData | `API#encrypt_message` / `#decrypt_message` | local | done |
+| BlazeClient send helpers | `API#blaze_send_*` | WebSocket | done |
+| **Inscriptions** |
+| ReadCollection / ReadInscription / ReadCollectionItems | `API#collection`, `#collectible`, etc. | safe inscriptions | done |
+| **Apps** |
+| Migrate | `API#transfer_app_ownership` | POST `/apps/:id/transfer` | done |
+| **Codes** |
+| ReadCode | `API#read_code` | GET `/codes/:id` | done |
+| **TIP** |
+| GetTipNodeByPath* | `API#get_tip_node` | GET `/external/tip/:path` | done |
+| TipBodyFor* | `API#tip_body_for_*` | local | done |
+| **Network misc** |
+| GetTurnServer | `API#turn_servers` | GET `/turn` | done |
+| CallKernelRPC | `API#rpc_proxy` | POST `/external/kernel` | done |
+| **Mix / invoice** |
+| NewUUIDMixAddress / NewMainnetMixAddress | `MixAddress` | local | done |
+| MixAddress.RequestOrGenerateGhostKeys | `MixAddress#request_or_generate_ghost_keys` | local/API | done |
+| NewMixinInvoice | `MixinBot::Invoice` | local | done |
+| **URL schemes** |
+| SchemeUsers / Transfer / Pay / … | `MixinBot::UrlScheme` | local | done |
+| **Utils** |
+| UniqueObjectId | `MixinBot.utils.unique_object_id` | local | done |
+| UniqueConversationId | `MixinBot.utils.unique_uuid` | local | done |
+| GroupConversationId | `MixinBot.utils.generate_group_conversation_id` | local | done |
+| Chunked / MakeUniqueStringSlice | `MixinBot.utils.chunked`, `#make_unique_string_slice` | local | done |
+| **Computer** |
+| GetComputerInfo | `MixinBot::Computer.info` / `API#get_computer_info` | computer.mixin.one | done |
+| GetComputerUser | `API#get_computer_user` | done |
+| GetComputerDeployedAssets | `API#get_computer_deployed_assets` | done |
+| GetComputerSystemCall | `API#get_computer_system_call` | done |
+| ComputerDeployExternalAsset | `API#computer_deploy_external_asset` | done |
+| LockComputerNonceAccount | `API#lock_computer_nonce_account` | done |
+| GetFeeOnXINBasedOnSOL | `API#get_fee_on_xin_based_on_sol` | done |
+| RegisterComputer | `API#register_computer` | done |
+| ComputerUserIDToBytes | `API#computer_user_id_to_bytes` | done |
+| BuildSystemCallExtra | `API#build_system_call_extra` | done |
+| EncodeOperationMemo / EncodeMtgExtra / DecodeComputerExtraBase64 | `API#encode_*` | done |
+| **BotAuth** |
+| NewBotAuthClient / SignRequest | `MixinBot::BotAuth` | local | done |
+| **Monitor** |
+| ReportToMonitor | `MixinBot::Monitor.report_to_monitor` | pipeline | done |
+| UnmarshalAppMessage | `MixinBot::Monitor.unmarshal_app_message` | local | done |
+| CheckRetryableError | `MixinBot::Monitor.check_retryable_error` | local | done |
+| **HTTP config** |
+| Request / SetBaseUri / SetBlazeUri | `MixinBot::Configuration`, `Client` | config | n/a |
+| NewSafeUser | `MixinBot::Configuration` | config | n/a |
+| cli/*, examples/*, mixin/rpc main | `mixinbot call` / `mixinbot list` | CLI dispatch to `MixinBot::API` | done |
+
+Update this file when adding or changing API surfaces. Run `rake mixin_bot:api_coverage` to ensure no `missing` rows remain.

data/CHANGELOG.md

@@ -0,0 +1,112 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- **`mixinbot call METHOD`** and **`mixinbot list`** — invoke any public `MixinBot::API` method from the CLI with JSON keyword arguments (`-d`).
+- **`mixinbot utils call`** / **`mixinbot utils list`** — same for `MixinBot.utils` helpers.
+
+### Changed
+
+- **`mixinbot transfer`** — uses Safe API (`create_safe_transfer`) instead of legacy `POST /transfers`.
+- **`mixinbot api`** — routes through `MixinBot::Client` (supports JSON array POST bodies); keystore loading includes `spend_key` and `client_secret`.
+- **`mixinbot updatetip`** — uses `update_tip_pin` instead of misusing `update_pin`.
+- **`mixinbot safetransfer`** — delegates to `transfer` (no duplicated signing pipeline).
+
+### Deprecated
+
+- **`mixinbot legacy-transfer`** — explicit legacy transfer command (replaces old default `transfer` behavior).
+- **`mixinbot safetransfer`** — use `transfer` instead.
+
+### Fixed
+
+- **`mixinbot nftmemo`** — calls `MixinBot.utils.nft_memo` (was a broken `nft` alias).
+
+## [2.0.0] - 2026-05-16
+
+### Added
+
+- `MixinBot.utils.hash_members` (Go `HashMembers`) for sorted member hashing; used by `safe_outputs` and legacy output/collectible helpers.
+- `MixinBot::API#tip_or_legacy_pin_payload` and adoption across legacy PIN/TIP call sites.
+- Offline WebMock harness (`test/support/mixin_api_stubs.rb`), deterministic `OfflineConfig`, and `rake test_live` (runs `test` with `LIVE=1`).
+- Golden-vector fixtures under `test/fixtures/golden/` and transaction hex under `test/fixtures/transactions/`.
+
+### Changed
+
+- **HTTP responses** — `MixinBot::Client` returns `MixinBot::Models::ApiEnvelope` (no `merge!` of `data` into the top level). One-liners such as `#me` still return the inner `data` hash where that was the historical contract.
+- **`MixinBot::API#build_safe_transaction`** — derives the mixin asset hash from each UTXO’s `asset_id` when `asset` is absent (matches API output shapes).
+- **`MixinBot::Transaction#decode`** — reads the `references` section only when `references` is non-empty, matching encode behavior (fixes Safe tx round-trips).
+
+### Deprecated
+
+- All `Legacy*` API modules emit `MixinBot.deprecator` warnings (silenced in the default test suite). Migrate to Safe APIs (`create_safe_transfer`, `build_safe_transaction`, `safe_outputs`, inscriptions, etc.).
+
+### Fixed
+
+- **Ruby 4.0** — declare the `benchmark` gem (stdlib is no longer auto-loaded), bump **`eth` ≥ 0.5.17** (compatible `openssl` stack), add **`rdoc`** for `rake`/YARD, replace **`CGI.parse`** in offline stubs with **`URI.decode_www_form`**, and run CI on **4.0**.
+
+## [1.5.0] - 2026-05-15
+
+### Changed (breaking)
+
+- **`MixinBot::API#safe_register`** — renamed the misleading first positional
+  parameter `pin` to `spend_key` and removed the previously unusable
+  `spend_key:` keyword argument. The method now takes a single argument:
+  the user's spend Ed25519 private key, accepted as raw bytes, hex, or a
+  Base64-encoded string. All in-tree call sites already used it positionally,
+  so most consumers will not need changes.
+
+  Migration:
+
+  ```ruby
+  # before
+  api.safe_register(spend_key_hex)                       # already worked
+  api.safe_register(pin, spend_key: spend_key_bytes)     # never worked correctly
+
+  # after
+  api.safe_register(spend_key_hex)
+  api.safe_register(spend_key_bytes)
+  ```
+
+### Fixed
+
+- **`MixinBot::API#create_safe_user`** — the per-instance `@__retry__`
+  counter leaked across calls and was not thread-safe. Replaced with a
+  local variable inside a private `with_safe_register_retries` helper.
+- **`MixinBot::API#migrate_to_safe`** — fixed a long-standing bug where
+  `safe_register pin, spend_key` raised `ArgumentError` (positional vs.
+  keyword mismatch) and additionally passed the TIP public key hex as the
+  signing key. Now correctly calls `safe_register(spend_key_hex)`.
+- **`MixinBot::API#safe_register`** — would crash inside
+  `JOSE::JWA::Ed25519.sign` when callers passed a 32-byte seed. Now
+  derives a normalized 64-byte signing key from the keypair before
+  encrypting the TIP PIN.
+
+### Improved
+
+- The Safe-network registration retry now rescues only transient
+  `MixinBot::PinError` / `MixinBot::ResponseError` (e.g. server-side TIP
+  PIN propagation lag), instead of swallowing every `MixinBot::Error`
+  including `UnauthorizedError`, `NotFoundError`, etc.
+- Added module-level constants for retry limits and propagation delay:
+  `SAFE_REGISTER_MAX_RETRIES`, `SAFE_REGISTER_RETRY_BASE_DELAY`,
+  `TIP_PIN_PROPAGATION_DELAY`.
+- Added input validation: `safe_register` now raises `ArgumentError` when
+  the spend key cannot be decoded into at least 32 bytes.
+- Added YARD documentation for `create_user`, `create_safe_user`,
+  `safe_register`, and `migrate_to_safe`, matching the style used in
+  `MixinBot::API::Me`.
+- Added a `# NOTE:` comment in `safe_register` clarifying that the Go
+  SDK's `crypto.Sha256Hash` is misleadingly named — it actually computes
+  SHA3-256, so `SHA3::Digest::SHA256` is the correct Ruby match.
+
+## [1.4.0] - prior
+
+See `CHANGES_SUMMARY.md` for the documentation overhaul that preceded this
+changelog.