Offline Multisig Signing Ceremony Workflow for Air-Gapped and Multi-Party Transaction Approval (starforge multisig ceremony)

[Nanle-code]

Problem Statement

StarForge already models multisig accounts (utils/multisig.rs) and supports hardware wallet signing (utils/hardware_wallet.rs), but there is no orchestrated workflow tying them together for the case that matters most for treasury and protocol-governance safety: an M-of-N transaction where each signer operates on a separate, potentially air-gapped machine, and no single machine ever holds enough signing authority to submit alone. Today, coordinating this requires signers to manually copy XDR blobs around and hope they combine them correctly.

Proposed Solution

Add a starforge multisig ceremony command family that manages the full lifecycle of a multi-party signing session as portable, self-describing files:

• starforge multisig ceremony start --source <G...> --op <...> --threshold 3 --signers <G1,G2,G3,G4> --output tx.ceremony — builds an unsigned transaction envelope plus a ceremony manifest (required signers, threshold, expiry ledger bound) into a single portable file.
• starforge multisig ceremony sign --input tx.ceremony --wallet alice [--hardware] --output tx.ceremony — a signer (potentially on an air-gapped machine, potentially using a connected Ledger device) adds their signature to the ceremony file and records who signed and when, without requiring network access.
• starforge multisig ceremony status --input tx.ceremony — reports collected vs. required signatures, which signers are outstanding, and time remaining before the transaction's time bounds expire.
• starforge multisig ceremony submit --input tx.ceremony --network mainnet — verifies the threshold is met, assembles the final signed envelope, and submits it, refusing to submit if signatures are insufficient, from unauthorized signers, or if the ceremony file has been tampered with (integrity-checked via a manifest hash).
• Ceremony files are plain, diffable, git-friendly text (base64/JSON) so they can be passed via USB drive, QR code export/import, or a shared repository/PR for auditability.

Technical Scope

• New src/utils/ceremony.rs: ceremony file format (versioned), manifest integrity hashing, signature collection/merge logic building on the existing multisig.rs primitives.
• New src/commands/multisig_ceremony.rs (or an extension of the existing multisig command module) wiring the four subcommands.
• Reuse the existing hardware wallet signing path for the --hardware flag rather than reimplementing device communication.
• Tamper detection: any modification to the unsigned transaction body after ceremony start must be rejected at sign or submit time.
• Tests: threshold math edge cases (exactly at threshold, below threshold, duplicate signer submission), tamper-detection rejection, expiry handling, and round-trip serialization of ceremony files.

Acceptance Criteria

• A 3-of-5 ceremony can be completed by simulating three independent sign invocations against the same file (no shared process state) and verified via status before submit.
• Attempting submit with only 2 of 3 required signatures is rejected with a clear error.
• A ceremony file that has been edited to alter the transaction body after the first signature is rejected at the next sign or submit step.
• Documentation walks through a full multi-machine ceremony example, including the air-gapped/USB-transfer use case.

Estimated Scope

Approximately 700 lines of new Rust across the ceremony engine, CLI wiring, and tests.

[JayCul]

Hi, I'd like to work on this issue because I have experience with Rust, multisig workflows, and cryptographic signing protocols and can deliver a clean PR.

I plan to implement an offline multisig signing ceremony workflow with start, sign, status, and submit commands, using portable JSON-based ceremony files with tamper detection, reuse existing hardware wallet support, and add comprehensive tests covering threshold logic, tamper detection, and round-trip serialization. Kindly assign it to me.

[neromtoobad]

Hi, I'd like to work on this issue. I designed and shipped the multisig admin flow this ceremony would sign for — OrbitChain's propose/approve/execute timelock governance (PR #203), where quorum collection across independent signers is the core mechanic — and my merged deploy CLI (#171) covers the key-handling side. I can deliver in 12 hrs. Looking forward to contributing.

[Emmy123222]

Hi, I’d like to contribute to this issue.

I’ve reviewed the problem statement, and I understand that the goal is to add a safe, orchestrated multisig ceremony workflow where multiple signers can independently sign the same transaction without any single machine holding enough signing authority to submit alone.

My proposed approach would be to:

1. Add a new src/utils/ceremony.rs module to define the ceremony file format, including:

   • Versioned JSON/base64 structure
   • Unsigned transaction envelope
   • Required signers
   • Signature threshold
   • Expiry/time-bound metadata
   • Manifest hash for tamper detection
   • Collected signatures and signer metadata

2. Implement the ceremony lifecycle commands:

   • starforge multisig ceremony start
   • starforge multisig ceremony sign
   • starforge multisig ceremony status
   • starforge multisig ceremony submit

3. Reuse the existing utils/multisig.rs primitives for threshold/signature validation and the existing utils/hardware_wallet.rs path for --hardware signing, instead of reimplementing signing logic.

4. Make the ceremony file portable and audit-friendly by keeping it plain text, diffable, and suitable for USB transfer, QR export/import, or review through a shared repository/PR.

5. Add tamper detection so any modification to the unsigned transaction body, signer set, threshold, or expiry metadata after ceremony creation is rejected during signing or submission.

6. Add tests covering:

   • Exact threshold success
   • Below-threshold rejection
   • Duplicate signer submission
   • Unauthorized signer rejection
   • Tampered ceremony-file rejection
   • Expired ceremony rejection
   • Round-trip serialization/deserialization
   • Independent signing across separate invocations with no shared process state

7. Add documentation showing a full multi-machine ceremony flow, including an air-gapped signer using USB transfer and an optional hardware wallet signing path.

I’d be happy to take ownership of this issue. Before I begin, are there any existing CLI conventions or ceremony-file format preferences you would like me to follow?

[grantfox-oss]

🦊 GrantFox — @Emmy123222 has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #59)
2. Your PR will be reviewed by the StarsForges maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign | FWC26 campaign!

@Emmy123222's PR #65 was approved and merged by @Nanle-code.

🏆 @Emmy123222: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (408 total points). Track your full progress on GrantFox.

👏 Great work, @Emmy123222! Keep contributing to StarsForges.