Skip to content

docs: Chain Fusion Signer usage guide#107

Merged
marc0olo merged 8 commits into
mainfrom
docs/guides-chain-fusion-signer
Apr 17, 2026
Merged

docs: Chain Fusion Signer usage guide#107
marc0olo merged 8 commits into
mainfrom
docs/guides-chain-fusion-signer

Conversation

@marc0olo
Copy link
Copy Markdown
Member

Summary

  • Adds guides/chain-fusion/chain-fusion-signer.md — a task-oriented guide for using the Chain Fusion Signer canister (grghe-syaaa-aaaar-qabyq-cai)
  • Covers: ICRC-2 cycle payment setup, Ethereum/Bitcoin address derivation (online + offline via @dfinity/ic-pub-key), ETH transaction signing, BTC send, generic ECDSA/Schnorr signing, web app integration pattern, fee reference table, and payment variant options
  • Also includes infrastructure: three new submodules (chain-fusion-signer v0.3.0, papi v0.1.1, ic-pub-key v1.0.1) with CLAUDE.md/VERSIONS updates and a decisions.md entry
  • Closes page-proposal: Chain Fusion Signer usage guide #24

Notes

  • All CLI examples use icp canister call (no dfx). The icp canister call command does not support --with-cycles without a proxy, so all examples use the CallerPaysIcrc2Cycles ICRC-2 pre-approval model, which is also the recommended approach for web apps.
  • The TypeScript web app snippet is annotated with <!-- Needs human verification --> — the actor creation pattern is correct in principle but should be verified against the actual generated bindings.
  • eth_sign_transaction example uses placeholder gas/fee values; real values depend on current network conditions.
  • Page uses inline code snippets throughout (no #region markers in .sources/examples for the signer).

Sync recommendation

Informed by dfinity/chain-fusion-signersrc/signer/canister/signer.did, src/signer/api/src/methods.rs, README.md, check-pricing.report.md; dfinity/papiREADME.md; dfinity/ic-pub-keyREADME.md, src/cli.ts

Adds three release-pinned submodules to support the chain-fusion signer
guide (page proposal #24):
- chain-fusion-signer v0.3.0 — signer canister API and key derivation
- papi v0.1.1 — ICRC-2 cycle payment interface
- ic-pub-key v1.0.1 — CLI tool for address/key derivation

Updates CLAUDE.md submodule table and bump checklist, VERSIONS, and
decisions.md.
Covers ICRC-2 cycle payment setup, Ethereum and Bitcoin address
derivation, transaction signing, generic ECDSA/Schnorr, web app
integration pattern, fee table, and offline address derivation via
@dfinity/ic-pub-key. Source: chain-fusion-signer v0.3.0, papi v0.1.1,
ic-pub-key v1.0.1.

Closes #24.

## Prerequisites

- An ICP identity with cycles in the [Cycles Ledger](https://learn.internetcomputer.org/hc/en-us/articles/34574082975252-Cycles-Ledger) (`um5iw-rqaaa-aaaaq-qaaba-cai`)
Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can't we link internally to reference/system-canisters/#cycles-ledger ? would be better IMO

@marc0olo
Copy link
Copy Markdown
Member Author

Feedback addressed:

  • Replaced both Learn Hub links to Cycles Ledger with internal links to reference/system-canisters.md#cycles-ledger
  • Added sidebar: order: 5 to frontmatter so the page appears after the existing chain guides (Bitcoin=1, Ethereum=2, Solana=3, Dogecoin=4) in the autogenerated navigation

@marc0olo
Copy link
Copy Markdown
Member Author

Review findings

Verified correct ✅

  • Canister ID (grghe-syaaa-aaaar-qabyq-cai) and Cycles Ledger ID (um5iw-rqaaa-aaaaq-qaaba-cai) — confirmed against canister_ids.json
  • All API method signatures and Candid argument ordering — confirmed against signer.did
  • All fee amounts — confirmed against src/signer/api/src/methods.rs at v0.3.0
  • icp canister call Candid syntax for all examples
  • Offline CLI flags (-u, -n) — confirmed against src/cli.ts
  • All payment type variants — confirmed against signer.did and papi/README.md
  • Internal links (system-canisters.md#cycles-ledger, bitcoin.md, ethereum.md)
  • <!-- Upstream: --> comment present and accurate
  • Build passes cleanly

Fixed in this PR ✅

  • icp generate signer.didnpx @icp-sdk/bindgen --did-file signer.did --out-dir — the icp generate command does not exist in icp-cli; replaced with the correct @icp-sdk/bindgen CLI tool

Minor suggestions (non-blocking)

  • The fee table version note (at v0.3.0) will become stale on next signer release — consider linking to the source instead of embedding the version label, or noting it's approximate
  • "~27 signing operations" comment in the approve section implicitly assumes 37B-cycle methods; a parenthetical clarification would help
  • The TypeScript snippet is already flagged with <!-- Needs human verification --> — the createActor import pattern should be verified against actual @icp-sdk/bindgen output once bindings are generated

@marc0olo marc0olo merged commit 8e35ebe into main Apr 17, 2026
1 check passed
@marc0olo marc0olo deleted the docs/guides-chain-fusion-signer branch April 17, 2026 13:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

page-proposal: Chain Fusion Signer usage guide

1 participant