Skip to content

Develop offline transaction signing utility for cold storage - #141

Merged
Lakes41 merged 1 commit into
Adamantine-guild:mainfrom
NkechiOgbuji:feat/offline-transaction-signer
Jul 29, 2026
Merged

Develop offline transaction signing utility for cold storage#141
Lakes41 merged 1 commit into
Adamantine-guild:mainfrom
NkechiOgbuji:feat/offline-transaction-signer

Conversation

@NkechiOgbuji

Copy link
Copy Markdown
Contributor

Closes #65

Description

This PR introduces an offline transaction signing utility that enables developers to securely sign transactions in completely air-gapped environments without requiring any network connectivity.

The existing SDK assumes an active connection to retrieve transaction metadata such as network information, gas configuration, and other chain state before signing. That approach makes it unsuitable for institutions or security-sensitive environments where private keys must never exist on an internet-connected machine.

To address this, I implemented a dedicated OfflineSigner module that separates transaction construction and signing from any network interaction. The signer requires all transaction parameters to be supplied explicitly by the caller, ensuring the signing process is fully deterministic and can run entirely offline.

What Changed

  • Added a dedicated OfflineSigner implementation under src/security.
  • Implemented offline transaction signing without relying on any RPC provider, wallet client, transport, or HTTP request.
  • Required callers to manually provide all transaction state needed for signing, including values such as nonce, gas configuration, chain ID, and transaction payload.
  • Added support for transaction serialization into a raw hexadecimal payload that can be broadcast later from a separate online machine.
  • Exported the new module through the package entry point.
  • Added comprehensive unit tests covering offline signing behaviour, transaction serialization, validation, and network isolation.
  • Added dedicated tests to ensure no network requests or RPC lookups are performed during the signing process.
  • Updated the README with documentation describing the complete offline signing workflow, including transaction preparation, offline signing, and later broadcasting.

Validation

The implementation was validated with focused unit and integration tests.

  • Offline signing tests pass successfully.
  • Network-isolation tests confirm that no RPC calls or HTTP requests are performed during signing.
  • Serialized transactions are successfully parsed and validated.
  • Signer recovery confirms that signed transactions originate from the expected account.
  • The implementation works with manually supplied transaction parameters without requiring any online services.

The repository also contains several pre-existing issues unrelated to this work. Minimal fixes were applied only where necessary to restore valid project configuration and allow the new module and tests to be compiled and executed.

Acceptance Criteria

  • ✅ Produces valid signed transactions without requiring network connectivity.
  • ✅ Generates serialized raw transaction payloads suitable for later broadcasting.
  • ✅ Prevents accidental RPC or provider lookups during signing.
  • ✅ Includes documentation describing the air-gapped signing workflow.
  • ✅ Includes comprehensive tests covering offline signing and network isolation.

Notes

A live eth_sendRawTransaction broadcast was not performed because the development environment used for validation does not have access to a blockchain node. Instead, the generated transactions were validated through serialization, parsing, and signer recovery to confirm that the payloads are correctly constructed and ready for broadcasting on a connected environment.

@Lakes41
Lakes41 merged commit 6831191 into Adamantine-guild:main Jul 29, 2026
1 check passed
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.

Develop Offline Transaction Signing Utility for Cold Storage

2 participants