contractless
/
Contractless-Web3-Wallets
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Contractless-Web3-Wallets/README.md

4.5 KiB
Raw Blame History

Contractless Web3 Wallet

This repository contains the Contractless browser wallet, its browser-safe cryptography and transaction codecs, and the JavaScript SDK used by websites to communicate with the wallet.

Repository Structure

web3_wallet/
|-- core/       Rust and WebAssembly wallet cryptography and transaction codecs
|-- extension/  Browser extension source and distributable wallet interface
|-- sdk/        JavaScript library for website and application integration
|-- tests/      Integration tests and complete working SDK usage examples
`-- mockups/    Design references used while developing the wallet interface

The components remain separated internally because they have different responsibilities:

  • core handles deterministic hashing, keys, wallet encryption, transaction inspection, encoding, signing, and message proofs.
  • extension owns wallet storage, approvals, application sessions, API communication, and the browser interface.
  • sdk gives websites a stable interface for detecting, connecting to, and requesting actions from the installed wallet.
  • tests verifies wallet integration and provides complete working example code for every supported SDK operation.

The SDK can be published independently later without separating the wallet's source today.

Build the Browser Extensions

Install Rust, wasm-pack, Node.js, and pnpm. From extension:

pnpm install
pnpm run build

The build compiles separate testnet and mainnet versions of core to extension/src/wasm/testnet and extension/src/wasm/mainnet. Both cores are bundled into each browser package so the wallet can enforce the selected network's address format and transaction codecs locally. Vite then creates separate unpacked packages:

extension/dist/chrome/
extension/dist/firefox/

Build a single browser target with:

pnpm run build:chrome
pnpm run build:firefox

The wallet stores testnet and mainnet API URLs separately. Testnet defaults to https://api.contractless.dev; mainnet remains unconfigured until a mainnet API is available. Wallets and active website sessions are isolated by network, and changing networks locks the active wallet.

See extension/README.md for temporary installation, Firefox validation, packaging, and Mozilla source-submission instructions.

Development Checks

Run the Rust tests from core:

cargo test

Run the TypeScript check from extension:

pnpm run check

Website Integration

Websites should use sdk/contractless.js instead of communicating with the injected browser provider directly. See sdk/README.md for connection, session, message-signing, and transaction-signing examples.

Private keys remain inside the extension. Websites receive only approved addresses, signatures, signed transaction bytes, and session-scoped access keys.

Integration Test

The tests/tests.html page verifies that a website can detect the extension, request a connection, retrieve the authorized wallet address, and disconnect the temporary application session. It also contains editable, copyable, end-to-end transaction examples for transfers, tokens, NFTs/RWAs, marketing, burning, and vanity addresses. Successful requests display the returned transaction ID, complete signed bytes, byte count, and API broadcast reply.

The tests are also the complete example-code documentation for using the SDK. Each available wallet action includes working source that developers can view, copy, and adapt directly for their own applications. This covers wallet detection, connection and session handling, address and balance requests, message signing, single-signature transactions, data transactions, and the complete dual-signature swap and loan process.

The dual-signature examples use the included PHP JSON storage endpoint. Serve the repository from its root directory with PHP:

php -S 127.0.0.1:8080 -t .

Then open:

http://127.0.0.1:8080/tests/tests.html

PHP creates tests/storage/dual-signatures/<transaction-hash>.json when the first wallet signs. The second wallet loads and updates that record, and the broadcast example loads both signatures from it. The web-server user must be able to write to tests/storage. JSON is used only to keep the example easy to follow; applications can use any backend language or database.

The unpacked browser extension must be installed and the wallet must be unlocked before approving the connection request. Opening the page through a file:// URL is intentionally unsupported because it has no trustworthy website origin.