feat(near): add baseline NEAR transaction parser

[shahan-khatchadourian-anchorage]

Second PR of the NEAR chain-support stack (stacked on #425). Implements baseline NEAR transaction parsing in this crate's conventions.

Stack: A1 (#425) -> A2 (this) -> A3 (intents preset) -> A4 (signature verification) -> B (identity + wiring) -> C (docs site) -> D (wallet-signed token metadata).

What this PR does

Adds baseline NEAR chain decoding to chain_parsers/visualsign-near:

• tx.rs: borsh-decodes a NEAR Transaction/SignedTransaction from hex or base64 input.
• actions.rs: renders each Action variant (Transfer, FunctionCall with a fail-closed JSON args decoder for ft_transfer/ft_transfer_call/ft_withdraw, generic label fallback for the rest).
• convert.rs: assembles the final payload (Network/From/To + per-action fields) via NearVisualSignConverter.
• fmt.rs/networks.rs: yoctoNEAR/Tgas decimal formatting, Mainnet/Testnet display.

Two design decisions worth calling out:

• tx.rs's input decoding uses this repo's shared visualsign::encodings::SupportedEncodings::detect + decode_hex convention (matching visualsign-solana's own from_string) rather than hand-rolling 0x-prefix stripping -- this repo's convention is to reuse the shared mechanism rather than hand-roll per chain. Added a regression test for the 0x-prefixed case.
• convert.rs omits execute_intents decoding for now -- that code depends on presets/intents/, which lands in A3, compiled unconditionally there (no feature gate in the final design, since every other preset in this repo is unconditional too).

A1's placeholder NearParserError enum is removed as dead code in favor of visualsign::vsptrait::TransactionParseError directly; the now-unused thiserror dependency is dropped with it.

Review fixes folded in

• NearVisualSignConverter::with_network(NearNetwork): external callers (e.g. parser_app) can now construct a testnet converter without making the network field public.
• Two stale module doc comments corrected: fmt.rs claimed a base58 helper that doesn't exist in this file; networks.rs claimed "system-account recognition" that was never implemented.
• payload_type switched from the generic "VisualSign" to "NearTx", matching every other chain crate's convention (visualsign-solana: "SolanaTx", visualsign-tron: "TronTx").
• Multi-action transactions now get an "Action" boundary label ahead of Transfer's/FunctionCall's own fields when there's more than one action -- without it, e.g. two transfers in one transaction rendered two identically-labelled "Amount" fields with nothing distinguishing which action each belonged to.
• Dependency manifest trimmed to only what this PR's own code uses; everything else moves to the PR that actually introduces its first usage.

Verification

• cargo test -p visualsign-near -- 24/24 pass.
• cargo clippy -p visualsign-near --all-targets -- -D warnings, cargo fmt --check -- clean.
• cargo check/clippy -p parser_app --no-default-features --features near -- clean (narrow-build variant).
• make -C src lint, make -C src test -- clean (default features; stock builds unaffected).
• Internal code review and security review both run against this diff; no findings above minor/informational (one dead-dependency cleanup already folded in).

[Copilot]

Pull request overview

Ports a baseline NEAR chain parser into the workspace’s VisualSign conventions by adding NEAR transaction envelope decoding, per-action rendering, and a NearVisualSignConverter that assembles NEAR transactions into SignablePayload fields.

Changes:

• Added NEAR transaction decoding from hex/base64 (including 0x-prefixed hex) into a NearTransaction wrapper.
• Implemented baseline NEAR action rendering (Transfer + FunctionCall with fail-closed decoding for select NEP-141 methods) and payload assembly via NearVisualSignConverter.
• Removed now-dead NEAR-specific error type and dropped the thiserror dependency.

Reviewed changes

Copilot reviewed 7 out of 8 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/chain_parsers/visualsign-near/src/tx.rs	Adds NEAR borsh decoding from hex/base64 into NearTransaction + regression tests.
src/chain_parsers/visualsign-near/src/actions.rs	Renders NEAR Action variants into VisualSign fields; includes selective JSON args decoding for common FT methods.
src/chain_parsers/visualsign-near/src/convert.rs	Converts NearTransaction into SignablePayload with network/from/to headers and per-action fields.
src/chain_parsers/visualsign-near/src/fmt.rs	Adds yoctoNEAR + Tgas fixed-decimal formatting helpers and tests.
src/chain_parsers/visualsign-near/src/networks.rs	Introduces NearNetwork enum and display names + tests.
src/chain_parsers/visualsign-near/src/lib.rs	Exposes NEAR modules and re-exports NearVisualSignConverter/NearTransaction; removes dead error enum.
src/chain_parsers/visualsign-near/Cargo.toml	Drops thiserror dependency from the NEAR chain crate.
src/Cargo.lock	Removes thiserror from the NEAR crate dependency list.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[shahan-khatchadourian-anchorage]

Added NearVisualSignConverter::with_network(NearNetwork) so external callers can construct a testnet converter without making the field public. See 6f3ba4e.

[shahan-khatchadourian-anchorage]

Fixed -- the doc comment claimed a base58 helper that doesn't exist in this file (bs58 is used later, in the intents preset's tests, not here). Updated to "yoctoNEAR, Tgas formatting helpers." See 6f3ba4e.

[shahan-khatchadourian-anchorage]

Fixed -- removed the stale "system-account recognition" claim; this file only defines NearNetwork and its display names. See 6f3ba4e.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 8 changed files in this pull request and generated no new comments.

Suppressed comments (2)

src/chain_parsers/visualsign-near/src/convert.rs:19

• payload_type is used elsewhere as a chain-specific tag (e.g. "EthereumTx", "SolanaTx", "TronTx"). Using the generic string "VisualSign" here makes NEAR payloads inconsistent and harder to identify downstream (CLI output, consumers that switch on payload_type). Consider switching this constant to a NEAR-specific tag (e.g. "NearTx").

/// Payload version emitted for NEAR transactions.
const PAYLOAD_VERSION: i64 = 0;
/// Payload type tag emitted for NEAR transactions.
const PAYLOAD_TYPE: &str = "VisualSign";

src/chain_parsers/visualsign-near/src/convert.rs:62

• When a NEAR transaction contains multiple actions, Transfer renders only an "Amount" field and FunctionCall renders "Method"/"Deposit"/"Gas" without an action-kind field. In multi-action transactions this can produce repeated/ambiguous labels (e.g. multiple "Amount" fields) with no clear action boundary. Consider injecting an "Action" label for these variants when tx.actions().len() > 1.

        for action in tx.actions() {
            fields.extend(render_action(action)?);
        }

[prasanna-anchorage]

Read through the baseline and exercised it locally against real borsh-encoded transactions -- a 2.5 NEAR transfer renders Network / From / To / Amount 2.5 NEAR with title Transfer, ft_transfer renders Method / Recipient / Amount / Memo / Deposit / Gas with 30 Tgas correct, a genuinely signed SignedTransaction round-trips through the signed-first path, and trailing garbage is rejected (borsh's Not all bytes read covers it, so from_string needs no explicit length check). 24 tests pass, clippy --all-targets -D warnings clean.

I also byte-decoded TRANSFER_HEX against the borsh wire format independently of near-primitives: 120 bytes, signer/pubkey/nonce/receiver/block_hash/1 action, deposit exactly 10^24 yocto, zero trailing. That was the one thing in the PR a compiler can't check, and it's correct.

Three comments below. Only the second is a design question; the others are small.

[prasanna-anchorage]

These assertions cover signer, receiver, and the action variant, but never the deposit -- so the amount encoded in TRANSFER_HEX is untested.

That matters more here than it looks: this fixture is the only hand-encoded wire bytes in the crate (everything else builds Action values through near-primitives, which can't disagree with itself). The amount is also the single field a signer is most likely to be defrauded on. As written, the fixture's deposit bytes could be edited to any value and this test stays green.

I decoded the bytes by hand and they are right -- exactly 10^24 yoctoNEAR -- so this is just pinning down what's already correct:

let near_primitives::action::Action::Transfer(transfer) = &tx.inner.actions()[0] else {
    panic!("expected Transfer");
};
assert_eq!(transfer.deposit.as_yoctonear(), 1_000_000_000_000_000_000_000_000);

[shahan-khatchadourian-anchorage]

Added the missing assertion — transfer.deposit.as_yoctonear() == 1_000_000_000_000_000_000_000_000, matching your independent hand-decode. TRANSFER_HEX's amount is now actually pinned, not just its variant.

[prasanna-anchorage]

_options is discarded, and the Network field on the next few lines comes from self.network instead -- fixed when the converter is constructed. I think that's the wrong channel, because options.metadata is exactly how the requester already supplies this everywhere else.

Compare the two existing patterns:

• Ethereum (multi-network) reads it per request: networks::extract_chain_id_from_metadata(options.metadata.as_ref()) in lib.rs:457.
• Tron (single network) hardcodes create_text_field("Network", "Tron") -- fine, because there's nothing to get wrong.

NEAR is multi-network but takes neither route. The problem is that with_network can't actually be used per request under the current architecture: TransactionConverterRegistry holds one Box<dyn VisualSignConverterAny> per chain (registry.rs:120), registered once at startup (parser/app/src/registry.rs:18-41). So whatever network the instance is built with at boot is baked in for the process lifetime, and a testnet transaction renders a confident NEAR Mainnet header with no request-level way to correct it. An incorrect network label on a signing screen is the kind of thing that reads as authoritative.

The blocker is that ChainMetadata's oneof only has Ethereum and Solana variants (generated/parser.rs:80-85), so there's no Near variant to read yet -- which is presumably why this went to constructor state. Options as I see them, roughly in order of preference:

1. Add a Near(NearMetadata { network }) variant to the proto and read it from options.metadata here, matching Ethereum. Most consistent, but pulls a codegen change into A2.
2. Keep with_network as-is for now but drop the Network field from the payload entirely until the metadata path exists -- omitting the field is safer than asserting a possibly-wrong one.
3. Land as-is with a TODO and an explicit note in stage B that registration must not assume mainnet.

Happy with any of these, and (1) is a reasonable thing to defer to B if you'd rather not grow this PR -- but I'd like the decision recorded rather than left implicit in the constructor. What's the plan for how B wires this?

[shahan-khatchadourian-anchorage]

Went with option 1: added NearMetadata { network_id } as a new variant on ChainMetadata's oneof (proto + codegen regen), and convert.rs now reads options.metadata per-request via a new extract_network_from_metadata — mirrors visualsign-ethereum's extract_chain_id_from_metadata almost line for line. Falls back to whatever network the converter was constructed with when metadata is absent or belongs to another chain.

This means stage B needs no changes: NearVisualSignConverter::new(), registered once at startup, is already the right pattern once this lands — same shape as EthereumVisualSignConverter::new(), a single per-process instance whose network is resolved per-request from metadata rather than baked in at construction. B's existing registration code was accidentally already correct.

Also refactored the one exhaustive match on the oneof (visualsign-ethereum's extract_chain_id_from_metadata) to a let-else, so it's non-exhaustive by construction — adding Near didn't require touching that crate, and neither will any future chain variant.

The REST gateway's ChainMetadataInput JSON discriminator doesn't need adding here either — stage D already has a CHAIN_NEAR variant wired to NearMetadata, written ahead of this proto change landing. It'll just compile once D rebases onto this.

[prasanna-anchorage]

A transaction with zero actions produces a complete, valid-looking payload: Network / From / To, titled NEAR Transaction (via the _ => arm in title_for), and no indication that nothing happens. I confirmed this renders rather than erroring.

An empty actions vec is well-formed borsh but not a meaningful thing to sign, and the rendered result is indistinguishable at a glance from a transaction whose actions simply weren't decoded -- which is the more dangerous reading, since the fallback arm in render_action deliberately renders unknown variants as a bare Action label. A signer can't tell "this does nothing" from "we didn't understand this."

Suggest rejecting it outright:

if tx.actions().is_empty() {
    return Err(VisualSignError::…("NEAR transaction has no actions".into()));
}

If there's a reason to keep rendering it, an explicit No actions field would at least make the emptiness visible.

[shahan-khatchadourian-anchorage]

Fixed — to_visual_sign_payload now rejects a NEAR transaction with zero actions (VisualSignError::ValidationError) instead of rendering a normal-looking payload. Added a test (rejects_transaction_with_no_actions) covering it.