@anywalletkit/wallet-near 0.0.0-stage → 0.1.3

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,105 @@
-# Temporary Holding Version
+# @anywalletkit/wallet-near
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+NEAR accounts at `m/44'/397'/i'` (SLIP-10 ed25519 — the NEAR Wallet / `near-seed-phrase`
+path; index 0 is what every NEAR wallet derives), pinned by golden vectors in
+`@anywalletkit/conformance`. No near-api-js: borsh is hand-written against the nearcore
+schema (byte-for-byte checked against `@near-js/transactions`), the node answers JSON-RPC,
+the account signs `sha256(borsh(tx))` with noble ed25519 and broadcasts with `send_tx`.
+
+```ts
+import WalletManagerNear from '@anywalletkit/wallet-near'
+
+const wallet = new WalletManagerNear(seedPhrase, { provider: ['https://free.rpc.fastnear.com', 'https://rpc.mainnet.near.org'] })
+const account = await wallet.getAccount(0)          // implicit account: 64-hex id = the public key
+await account.transfer({ recipient: 'alice.near', amount: 10n ** 24n })                              // 1 NEAR (yocto)
+await account.transfer({ token: 'usdt.tether-token.near', recipient: 'alice.near', amount: 1_000_000n, memo: 'rent' }) // NEP-141
+await account.sendTransaction({ receiverId: 'wrap.near', actions: [{ functionCall: { methodName: 'near_deposit', args: {}, gas: 30n * 10n ** 12n, deposit: 10n ** 24n } }] })
+const sig = await account.sign('hello')             // "ed25519:<base58>" over the raw bytes
+const nep413 = await account.signNep413({ message, nonce, recipient: 'intents.near' }) // what NEAR Intents / dApps ask for
+const named = await wallet.getNamedAccount('alice.near') // same key, bound to a named account
+wallet.dispose()
+```
+
+## What happens before a signature
+
+Every `signTransaction` / `sendTransaction` / `transfer` goes through the same gate:
+
+1. **Build**: `signerId` / `publicKey` are the account's; `nonce` = access-key nonce + 1 and
+   `blockHash` = the latest final block come from the node (so `needsNetwork` is true).
+2. **Hard checks** (`UnsafeTransactionError`, with a `code`): the signer and key are this
+   account; at least one action; no *dangerous* action — AddKey, DeleteKey, DeleteAccount,
+   DeployContract, Stake, CreateAccount, global-contract actions, SignedDelegate — unless
+   `allowDangerousActions: true`; a valid receiver id; prepaid gas ≤ 300 Tgas; fee ≤
+   `transactionMaxFee` when set.
+3. **Preflight** (`SimulationError`, off with `simulate: false`) — NEAR has no dry-run RPC, so
+   this is what makes a transaction fail *before* a fee is paid: the signer account and its
+   access key exist and allow the call, the spendable balance (total − locked − storage) covers
+   deposits + fee, a named recipient exists (an implicit one may be created, for ≥ 0.002 NEAR),
+   the NEP-141 balance covers an `ft_transfer`, the recipient is registered on the token or a
+   `storage_deposit` rides along.
+4. **Fee estimate** (upper bound: prepaid gas counts in full; unused gas is refunded; a native
+   transfer that creates an implicit account adds the protocol's ~0.007 NEAR creation charge —
+   measured on mainnet, not derivable from gas) and the `transferMaxFee` / `transactionMaxFee` cap.
+
+Measured on mainnet (2026-10-10): `ft_transfer` 11.6 Tgas / 0.00041 NEAR; native transfer creating
+the recipient 15.9 Tgas / 0.0071 NEAR.
+
+`describeTransaction(tx)` tells you what a transaction does, offline: `near-transfer`,
+`ft-transfer` (recipient / amount / memo decoded from the args), `ft-storage-deposit`,
+`function-call`, `batch`, or the dangerous kinds — with warnings (`dangerous-action`,
+`full-access-key`, `zero-amount`, `self-transfer`, `high-gas`, `unknown-method`,
+`invalid-account`). `account.describeTransactionOnline(tx)` adds `implicit-new-account`.
+
+## NEP-141 tokens
+
+`transfer({ token, recipient, amount, memo })` sends `ft_transfer` with 1 yoctoNEAR and 30 Tgas.
+When the recipient is not registered on the token (`storage_balance_of` is null) a
+`storage_deposit` for `storage_balance_bounds.min` (0.00125 NEAR on most tokens) is prepended
+in the same transaction. `getTokenBalance(token)` is `ft_balance_of`.
+
+## Accounts
+
+An implicit account exists from the first NEAR it receives; an account holding only tokens and
+no NEAR cannot sign (nothing pays gas) — `simulateTransaction` reports that. A named account
+(`alice.near`) that lists this key as a full-access key works through `getNamedAccount`.
+`getBalance()` is the total; `getAvailableBalance()` is what can be spent.
+
+## Network
+
+`provider` is one or more JSON-RPC urls (or custom transports); a list fails over in order,
+except for definitive node answers (unknown account, invalid transaction) which are returned
+as they are. `rpc.mainnet.near.org` is rate-limited and deprecated for production — use
+FastNear / a provider / your own proxy. CAIP-2: `near:mainnet` (default) or `near:testnet`.
+
+## Activity history
+
+`createNearHistory` is the chain's `HistorySource` (`@anywalletkit/core`) over the nearblocks API, optionally sharpened by an archival RPC.
+
+```ts
+import { createNearHistory } from '@anywalletkit/wallet-near/history'
+
+const history = createNearHistory({ apiKey: process.env.NEARBLOCKS_KEY, rpcUrl: 'https://archival-rpc.mainnet.near.org' })
+const page = await history.listActivity('fc647e203e0e099212485017b78a0e77dc330019d4b532a4d44408adc0bfd9a1', { limit: 25 })
+const older = await history.listActivity(address, { cursor: page.cursor })
+const one = await history.getTransaction(page.items[0].hash, address)
+history.explorerTxUrl(one.hash) // https://nearblocks.io/txns/…
+```
+
+| option | default | notes |
+|---|---|---|
+| `nearblocksUrl` | `https://api.nearblocks.io` (`api-testnet.nearblocks.io`) | |
+| `apiKey` | none | Bearer key. Keyless nearblocks is limited to a few requests per minute. |
+| `rpcUrl` | none | `EXPERIMENTAL_tx_status` for `getTransaction`. Must be **archival** for anything older than a few days: `rpc.mainnet.near.org` answered `UNKNOWN_TRANSACTION` for a two-week-old hash, `archival-rpc.mainnet.near.org` served it. |
+| `network` | `mainnet` | `near:mainnet` / `near:testnet`. |
+| `rateLimit` | 0.1 rps (6/min) keyless, 5 with a key | nearblocks requests per second; a page needs two. |
+| `fetch`, `timeoutMs` | global, 15 000 | |
+
+**Lists.** `GET /v1/account/{id}/txns?per_page=&order=desc&cursor=` (receipt-level rows, asked for twice the limit since a transaction usually has a call and a refund receipt) and `GET /v1/account/{id}/ft-txns?per_page=&order=desc&cursor=` (NEP-141 movements), grouped by `transaction_hash`. nearblocks writes large yoctoNEAR values as JSON numbers; bodies go through `parseJsonPreservingBigInts`, which re-quotes 16+ digit integer literals before `JSON.parse` so they stay exact, while values nearblocks had already rounded to a double (`7e+23`) are used as-is and flag the row `raw.approximate`. `delta_amount` of NEP-141 rows is a string and always exact.
+
+**Mapping.** Receipt rows whose predecessor is `system` (gas refunds) carry no transfers. `TRANSFER` actions and `FUNCTION_CALL` deposits (other than the NEP-141 one-yoctoNEAR formality) become native transfers predecessor → receiver; the first non-transfer action of the receipt addressed to someone else becomes `call` (`to` = receiver, `method`, `programs` = every method in order). NEP-141 rows become `nep141` transfers with the contract as `token`, `symbol` / `decimals` from `ft` (an `ft_transfer_call` into `intents.near` is own → `intents.near`, what `@anywalletkit/protocol-swap2-near-intents` looks for). `status` from `outcomes.status`, `fee` from `outcomes_agg.transaction_fee`, `block` = the lowest `block_height` of the group, `time` from the transaction's `block_timestamp`.
+
+**Cursor.** Base64 JSON `{ v: 1, tx, ft }`: the `id` / `event_index` of the last consumed row of each list (`''` = not started, `null` = exhausted) — nearblocks' `cursor=` is a keyset, so the page can take the top `limit` transactions by block time plus ties and resume each list exactly where it stopped; a list that came back short and fully consumed is not asked again. Receipts of one transaction share the transaction's `block_timestamp`, so a transaction is never split across pages (an NEP-141 row carries its receipt's block time and may land one page later as a row of its own).
+
+**Single transaction.** `GET /v1/txns/{hash}` (transaction-level actions, signer / receiver, `receipts[].fts` with **double** deltas → `raw.approximate`). With `rpcUrl`, `EXPERIMENTAL_tx_status(hash, signer)` rebuilds the row exactly: native legs from `Transfer` / `FunctionCall` deposits (delegate actions unwrapped, so `call.to` is the real receiver), NEP-141 legs from receipt logs (`EVENT_JSON` nep141 `ft_transfer` / `ft_mint` / `ft_burn` and the legacy `Transfer N from A to B` line `wrap.near` emits), `fee` = Σ `tokens_burnt`, `status` from `Failure`; `raw.rpc` holds the result. An RPC that does not know the hash or is down leaves the nearblocks row in place.
+
+Fixtures in `test/fixtures/history/` were captured on 2026-10-14 from `api.nearblocks.io` (keyless) and `archival-rpc.mainnet.near.org`: the test wallet's `/txns` page (a NEAR send with its refund receipt, a `storage_deposit` + `ft_transfer` call, a receive from `intents.near`) and its empty `/ft-txns`, plus — because the test wallet has no NEP-141 rows — the `/txns`, `/ft-txns`, `/v1/txns/{hash}` and RPC `EXPERIMENTAL_tx_status` of the NEAR Intents module's fixture transaction `Fdk3i7f9…` (20.5 wNEAR `ft_transfer_call` into `intents.near` by `b1633df6…`). `test/history.test.ts` checks that the near-intents module describes both the list row and the RPC-refined row as `Bridged wNEAR`.