Add TypeScript and Go Rosetta integration examples by dkijania · Pull Request #18833 · MinaProtocol/mina

dkijania · 2026-05-07T13:52:27Z

Summary

Adds runnable Rosetta integration examples — TypeScript (full Construction API flow including signing) and Go (read-side, using coinbase/mesh-sdk-go) — co-located with the Rosetta server source under src/app/rosetta/examples/.

Why this lives here, not in a separate repo

Same rationale as src/app/rosetta/docker-compose/: co-location with the daemon kills drift. When a Rosetta endpoint changes, the example breaks in the same PR a reviewer is looking at. Separate-repo example projects (cf. dfinity/rosetta-client, archived 2025-08) tend to die without strong ownership. Examples ship with the daemon, version-aligned automatically.

TypeScript (`examples/ts/`)

Script	Purpose
`account-balance.ts`	Smoke test for `/account/balance`
`scan-blocks.ts`	Polling loop fetching blocks from chain tip
`track-deposits.ts`	Filter `payment_receiver_inc` operations for an address
`send-transaction.ts`	Full Construction API flow using `mina-signer`'s `rosettaCombinePayload` helper
`offline-sign.ts`	Cold-signing variant: build payloads online, sign offline, submit online

commons.ts wraps the endpoints with a thin RosettaClient class and provides buildTransferOperations() for the three-operation MINA transfer layout (fee_payment + payment_source_dec + payment_receiver_inc). Uses axios + mina-signer; no Rosetta SDK dependency.

There is no maintained TypeScript Rosetta SDK. Coinbase's mesh-ecosystem lists exactly one JavaScript option (dfinity/rosetta-client), which was archived August 2025. Cardano's official Rosetta examples (input-output-hk/cardano-rosetta) use the same pattern as this PR.

Go (`examples/go/`)

Program	Purpose
`account-balance/`	Smoke test
`scan-blocks/`	Polling loop via `fetcher.NetworkStatus` + `fetcher.Block`
`track-deposits/`	Filter operations server-side

Send-transaction is intentionally not in Go: Pallas signing has no pure-Go implementation today. Integrators either shell out to mina-ocaml-signer or use the TypeScript offline-sign.ts. The Go examples cover the read-side patterns (balance, block, status) that real exchange integrators run from their main service.

internal/config/config.go centralizes the Mina-specific knobs (Blockchain="mina", CurveType=Pallas, default token ID, MINA currency).

The Go module path uses github.com/coinbase/rosetta-sdk-go because that is the canonical module path the SDK still ships under, even though the GitHub repo was renamed to mesh-sdk-go.

Testing

TypeScript: npm run typecheck passes against mina-signer@^3.0.7. Each script loads cleanly and reaches the network layer (verified via connection-refused path).
Go: code reviewed against the live coinbase/mesh-sdk-go API surface. Local Go toolchain too old for go vet, awaiting CI.
End-to-end runtime validation against a live devnet Rosetta is the obvious next step before this is recommended in user-facing docs.

Test plan

cd src/app/rosetta/examples/ts && npm install && npm run typecheck
cd src/app/rosetta/examples/go && go mod download && go vet ./...
Spin up a devnet Rosetta via src/app/rosetta/docker-compose/
cp ts/env.example ts/.env, fill in TEST_ADDRESS, run cd ts && npm run account-balance
npm run scan-blocks and observe new blocks appearing
(with funded devnet keypair) npm run send-transaction end-to-end
cd go && TEST_ADDRESS=B62q... go run ./account-balance

🤖 Generated with Claude Code

Runnable scripts under src/app/rosetta/examples/ts/ demonstrating common Mina Rosetta integration patterns: - account-balance.ts: smoke test for /account/balance - scan-blocks.ts: polling /network/status + /block - track-deposits.ts: filtering operations for payment_receiver_inc - send-transaction.ts: full Construction API flow using mina-signer's rosettaCombinePayload helper - offline-sign.ts: cold-signing variant splitting the flow across online/offline phases via on-disk handoff commons.ts wraps the endpoints with a thin RosettaClient and provides a buildTransferOperations helper for the three-operation MINA transfer layout. Uses axios + mina-signer; no Rosetta SDK dependency. Co-located with the Rosetta server source so examples stay in sync with the daemon they target. Matches the docker-compose pattern. README files explain setup and link to the docs portal for narrative context. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

When Rosetta is not reachable, surface the configured URL and a hint in the thrown Error rather than letting the raw AxiosError propagate. Makes the most common setup-time failure self-diagnosing. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Read-side companions to the TypeScript examples, using mesh-sdk-go's fetcher package — the canonical Go SDK Coinbase ships and uses internally. Programs added under src/app/rosetta/examples/go/: - account-balance/: smoke test - scan-blocks/: polling loop via fetcher.NetworkStatus + Block - track-deposits/: filter payment_receiver_inc operations for an address internal/config/config.go centralizes the Mina-specific knobs (blockchain="mina", curve_type=pallas, default token ID, MINA currency). Send-transaction is intentionally not in Go: Pallas signing has no pure-Go implementation, so integrators either shell out to mina-ocaml-signer or use the TypeScript offline-sign.ts. The Go examples cover the read-side patterns (balance, block, status) that real exchange integrators run from their main service. The Go module path uses github.com/coinbase/rosetta-sdk-go because that is the canonical module path the SDK still ships under, even though the GitHub repo was renamed to mesh-sdk-go. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

TypeScript SDK for Mina's Rosetta (Coinbase Mesh) endpoints. Companion to mina-signer — this SDK handles the typed HTTP surface (Data + Construction APIs); mina-signer handles cryptography. Surface (mirrors the canonical Rosetta operations): - Data API: networkList / networkStatus / networkOptions / block / accountBalance / mempool / searchTransactions - Construction API: derive / preprocess / metadata / payloads / combine / parse / hash / submit - post<T>() escape hatch for any other endpoint via the same retry path - Retry on transport / 5xx / `retriable: true` Rosetta errors; never on non-retriable Rosetta errors (deterministic by spec) - ClientConfig: baseUrl / network / retries / retryDelayMs / timeoutMs / headers / fetch (overridable) Mina-specific helpers: - buildTransferOperations — canonical 3-op layout (fee_payment + payment_source_dec + payment_receiver_inc) with the related_operations link the Rosetta spec requires - buildDelegationOperations — fee_payment + delegate_change - OperationType enum, MINA_CURRENCY, CURVE_TYPE, DEFAULT_TOKEN_ID constants Tests: 22/22 unit pass (12 client w/ mock fetch + 10 helpers). Examples account-balance / scan-blocks / track-deposits / send-transaction / offline-sign translated from MinaProtocol/mina#18833's inline commons.ts to use the SDK. Once this releases, that PR will be updated to depend on this package instead. CI: ci.yml (build + lint + tests), release.yml (npm publish via NPM_TOKEN on v* tag + GH release). No integration workflow yet — Rosetta fixture infra is heavier than the archive-node SDK's static SQL fixture; add later if there's a clear test profile. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

The PR's original `commons.ts` (300 lines: typed RosettaClient + Mina operation builder) has graduated into its own published-on-npm SDK at `o1-labs/mina-rosetta-sdk-js`. The examples now consume it as a regular dependency. - `commons.ts` deleted (−300 lines). - `package.json`: `axios` removed (HTTP is the SDK's concern now); `@o1-labs/mina-rosetta-sdk@^0.0.1` added; `dotenv` + `mina-signer` kept. - Each example imports types/client/helpers from the SDK; `requireEnv` + `sleep` inlined per-file so each script stays self-contained for copy-paste reading. - README updated: "no Rosetta TS SDK exists" → "install the SDK directly", drops the layout entry for `commons.ts`. - `package-lock.json` removed for now — the SDK is not yet on npm, so `npm ci` would fail anyway. Will regenerate once the SDK publishes `0.0.1`. The other PR docs in MinaProtocol/docs2#1201 don't depend on this lockfile. Net: −780 lines across the directory; example code-to-comment ratio improves and "what does this example actually do" reads faster. Blocks on: @o1-labs/mina-rosetta-sdk@0.0.1 being published to npm (awaiting NPM_TOKEN regeneration on the shared o1-labs account). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

The runnable mina-repo TS examples now depend on @o1-labs/mina-rosetta-sdk (published to npm 2026-05-13) rather than the inline axios+commons.ts pattern this PR originally documented. Refresh prose accordingly: - index.mdx setup paragraph: "axios + commons.ts" → SDK + signer - index.mdx "Why no SDK?" callout: pivots from "Mina follows the hand-rolled axios pattern" to "Mina ships its own SDK; upstream Coinbase still has the same gap for everyone else" - index.mdx network-identifier note: "RosettaClient in commons.ts" → "SDK's RosettaClient" - send-transactions.mdx: buildTransferOperations attribution follows the helper into the SDK Regenerate llms-full.txt accordingly. Pairs with MinaProtocol/mina#18833. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…a-sdk The top-level examples/README.md still described the ts/ subdir as "Cardano-style: axios + thin endpoint wrappers + No SDK dependency". That framing was accurate when the PR was first opened but stale after the migration to @o1-labs/mina-rosetta-sdk in 40e3c16. Refresh to describe the actual current state without the external chain comparison. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

dkijania · 2026-05-14T21:22:44Z

!ci-build-me

dkijania and others added 2 commits May 7, 2026 15:25

github-project-automation Bot added this to Mesa Triage May 7, 2026

github-project-automation Bot moved this to To triage in Mesa Triage May 7, 2026

dkijania mentioned this pull request May 7, 2026

Rewrite Rosetta samples as wrappers over mina-repo examples MinaProtocol/docs2#1201

Draft

3 tasks

dkijania changed the title ~~Add TypeScript Rosetta integration examples~~ Add TypeScript and Go Rosetta integration examples May 7, 2026

dkijania mentioned this pull request May 13, 2026

Create mina-bootstrap — unified setup tool for archive dumps, precomputed blocks, ledgers #18842

Open

6 tasks

dkijania and others added 2 commits May 14, 2026 23:06

small corrections for docs

4321f73

dkijania merged commit b02069b into develop May 14, 2026
28 of 30 checks passed

dkijania deleted the dkijania/rosetta-ts-examples branch May 14, 2026 22:14

github-project-automation Bot moved this from To triage to Done in Mesa Triage May 14, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add TypeScript and Go Rosetta integration examples#18833

Add TypeScript and Go Rosetta integration examples#18833
dkijania merged 6 commits into
developfrom
dkijania/rosetta-ts-examples

dkijania commented May 7, 2026 •

edited

Loading

Uh oh!

dkijania commented May 14, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

dkijania commented May 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Why this lives here, not in a separate repo

TypeScript (examples/ts/)

Go (examples/go/)

Testing

Related

Test plan

Uh oh!

dkijania commented May 14, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

dkijania commented May 7, 2026 •

edited

Loading

TypeScript (`examples/ts/`)

Go (`examples/go/`)