135 lines
4.6 KiB
Markdown
135 lines
4.6 KiB
Markdown
# 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
|
|
|
|
```text
|
|
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`:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
extension/dist/chrome/
|
|
extension/dist/firefox/
|
|
```
|
|
|
|
Build a single browser target with:
|
|
|
|
```text
|
|
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`:
|
|
|
|
```text
|
|
cargo test
|
|
```
|
|
|
|
Run the TypeScript check from `extension`:
|
|
|
|
```text
|
|
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.
|
|
|
|
The wallet's data-handling practices are described in the
|
|
[Privacy Policy](PRIVACY_POLICY.md).
|
|
|
|
## 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:
|
|
|
|
```text
|
|
php -S 127.0.0.1:8080 -t .
|
|
```
|
|
|
|
Then open:
|
|
|
|
```text
|
|
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.
|