docs: Rosetta DeFi guide

[marc0olo]

Summary

• ICP Rosetta vs ICRC Rosetta comparison and when to use each
• Running ICP Rosetta (Docker, from source, Validation Cloud) and ICRC Rosetta (single-token, multi-token)
• Data API: balance queries, block fetching, transaction search, NNS governance queries
• Construction API: key generation (Ed25519/secp256k1), operation types for ICP and ICRC
• Requirements: 24-hour transaction timing window, signature schemes, UTXO limitations

Sync recommendation

informed by dfinity/portal — docs/developer-docs/defi/rosetta/

[marc0olo]

Review: Rosetta API

Must fix

• Incomplete ICP operations list: The Construction API operations table (lines 441–452) omits several valid operations supported by ICP Rosetta. According to the portal's data_api/index.mdx (the /network/options response), the full list also includes MINT, BURN, APPROVE, FEE, CHANGE_AUTO_STAKE_MATURITY, NEURON_INFO, and LIST_NEURONS. These are real construction operation types. Omitting them without explanation will mislead exchange operators who encounter them in the wild. Either add them to the list or add a note that the list covers the most common governance operations and link to the full network/options output.

• Version inconsistency for ICRC Rosetta multi-token support: The comparison table says "Multi-token support (v2.1.0+)" and the multi-token section heading also says "(v2.1.0+)", but both Docker examples in that section use dfinity/ic-icrc-rosetta-api:v1.2.7 — a version well below 2.1.0. This is contradictory: either the feature exists before v2.1.0 and the annotation is wrong, or the examples use a tag that doesn't support multi-token. The portal source (icrc_rosetta/running-rosetta.mdx) also uses v1.2.7 with multi-token flags, which suggests the feature predates v2.1.0. The version annotation should be corrected or removed, and the Docker tag should reflect an accurate minimum version.

• Frontmatter description understates scope: The description reads "Integrate with exchanges and block explorers using the Rosetta API for ICP and ICRC-1 tokens". The page covers construction, staking, and NNS governance — none of which appear in the description. Update to reflect actual scope, e.g. "Run a Rosetta node for ICP or ICRC-1 tokens; query balances and blocks; construct and sign transactions offline; manage NNS neurons."

Suggestions

• ICRC Rosetta construction section is thin: The ICRC Rosetta operations section is three sentences. The portal's icrc_rosetta/construction_api/index.mdx documents both TRANSFER and APPROVE+SPENDER (ICRC-2) operation types. The page only mentions TRANSFER. Exchange operators integrating ICRC-2 will hit the missing APPROVE operation with no guidance. Consider adding the APPROVE/SPENDER case or a link to the portal construction API.

• No mention of --network-type mainnet for ICRC Rosetta production: The portal's ICRC Rosetta FAQ documents --network-type mainnet as the flag required to connect to mainnet. This flag is absent from all ICRC Rosetta examples. Readers following the production examples may not realize a flag is needed to target mainnet. Add it to the production Docker examples or add a callout.

• "Coinbase (now Mesh)" parenthetical is misleading: The open Rosetta specification remains called "Rosetta" — the "Mesh" rebrand refers to Coinbase's commercial API product, not the open specification. Consider dropping the parenthetical or rewording to: "developed by Coinbase (the open specification is sometimes called the Mesh API in Coinbase's developer platform)."

• Construction flow is missing optional standard endpoints: The official Rosetta spec also defines construction/parse and construction/hash. These are not required for the basic flow but are used by some integrators to verify transactions before broadcast. A brief note that these exist (and are supported) would help operators who encounter them.

• Scanability of "Data API" section: The section heading "Data API" spans network queries, balance queries, block fetching, transaction search, AND NNS governance calls. A reader scanning headings can't tell the section includes governance queries. The sub-heading "ICP-specific: NNS governance queries" already helps, but the opening intro paragraph could list the sub-sections to orient skimmers.

Verified

• All internal links resolve: token-ledgers.mdx and ../../reference/token-standards.md both exist at the expected paths.
• ICP ledger canister ID ryjl3-tyaaa-aaaaa-aaaba-cai confirmed against icrc-ledger skill and portal source.
• NNS governance canister ID rrkah-fqaaa-aaaaa-aaaaq-cai confirmed against portal icp_rosetta/index.mdx.
• ckBTC canister ID mxzaz-hqaaa-aaaar-qaada-cai and ckETH ss2fx-dyaaa-aaaar-qacoq-cai confirmed against icrc-ledger skill and portal source.
• Test token canister IDs (TICRC1, ckTestBTC, ckTestETH) confirmed against portal icrc_rosetta/running-rosetta.mdx.
• Test ICP ledger canister ID xafvr-biaaa-aaaai-aql5q-cai confirmed against portal icp_rosetta/index.mdx.
• Docker image names dfinity/rosetta-api and dfinity/ic-icrc-rosetta-api confirmed against portal source.
• Bazel build targets confirmed against portal icp_rosetta/running-rosetta.mdx and icrc_rosetta/running-rosetta.mdx.
• ICP Rosetta default port 8081, ICRC Rosetta default port 8082 confirmed against portal source.
• 24-hour transaction timing constraint confirmed against portal source.
• search/transactions 10,000 block limit confirmed against portal data_api/index.mdx.
• Construction API 6-step flow (derive, preprocess, metadata, payloads, combine, submit) confirmed against portal construction_api/operations-flow.mdx.
• <\!-- Upstream: --> comment present at end of file covering all referenced portal pages.
• No dfx references. No banned internetcomputer.org/docs or docs.internetcomputer.org links.
• File is .md (correct — no interactive components requiring .mdx).
• Frontmatter is complete (title, description, sidebar.order present).
• Data API examples use consistent network_identifier values matching the described node type.
• NNS governance call examples (get_pending_proposals, get_proposal_info, list_known_neurons) confirmed against portal data_api/index.mdx.
• Key generation OpenSSL commands are consistent with Ed25519 and secp256k1 support described in the text.
• All curl examples use localhost (not 0.0.0.0 as in the portal), which is more portable for macOS readers.

[marc0olo]

<!-- feedback-addressed -->

Feedback addressed for PR #87 — Rosetta API

Changes applied

Must fix:

1. Incomplete ICP operations list — Added the missing operation types to the ICP operations section: MINT, BURN, APPROVE, FEE, CHANGE_AUTO_STAKE_MATURITY, NEURON_INFO, LIST_NEURONS. Confirmed against portal icp_rosetta/data_api/index.mdx — the network/options response in the source shows exactly these operations in the allow.operation_types array. Reorganized the list into "Token operations" and "Neuron and governance operations" groups for clarity.

2. Version inconsistency for ICRC Rosetta multi-token support — Removed the (v2.1.0+) annotation from both the comparison table and the multi-token section heading. The portal source (icrc_rosetta/running-rosetta.mdx) uses v1.2.7 for multi-token examples; the annotation was inconsistent with the Docker tag actually shown. Removing the annotation avoids contradicting the concrete Docker examples.

3. Frontmatter description understates scope — Updated description to: "Run a Rosetta node for ICP or ICRC-1 tokens; query balances and blocks; construct and sign transactions offline; manage NNS neurons." This reflects the actual coverage (running nodes, data API, construction API, NNS governance).

Suggestions applied:

4. ICRC Rosetta construction section — APPROVE/SPENDER — Expanded the ICRC Rosetta operations section to describe both TRANSFER (ICRC-1) and APPROVE+SPENDER (ICRC-2) operation types. Confirmed against portal icrc_rosetta/construction_api/index.mdx.

5. --network-type mainnet flag for production ICRC Rosetta — Added --network-type mainnet to both the single-token and multi-token production Docker examples. Confirmed against portal icrc_rosetta/index.mdx FAQ: "Use the flag --network-type mainnet when starting your ICRC Rosetta node."

6. "Coinbase (now Mesh)" parenthetical — Reworded to: "the open specification is sometimes referred to as the Mesh API in Coinbase's developer platform, but remains called 'Rosetta' in the broader ecosystem."

7. Optional construction/parse and construction/hash endpoints — Added a note after the 6-step construction flow listing these two optional endpoints and their use cases.

8. Data API section scanability — Updated opening intro to explicitly list sub-sections: network information, account balances (including neuron balances), block fetching, transaction search, and ICP-specific NNS governance queries.

Items skipped

None. All feedback items were factually correct and verified against portal source material.

Build note

npm run build fails on this branch due to a pre-existing issue unrelated to rosetta.md: docs/guides/backends/https-outcalls.mdx references a file in .sources/examples/motoko/send_http_get/ which requires the examples submodule initialized. This failure exists on the unmodified branch (confirmed by stashing changes and running the build).