Skip to content

docs: make the install instructions work #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pauldelucia merged 1 commit into from
Aug 4, 2026
Merged

docs: make the install instructions work #6

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 9 additions & 32 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,13 @@

Python SDK for Willow — a decentralized data indexing protocol with cryptographic proof verification.

> **Install from source.** Willow's SDKs are not yet published to package registries.
> The commands below install directly from this repository and work today.

## Installation

```bash
pip install willow-sdk
pip install git+https://github.com/willow-network/willow-sdk-python.git
```

Or install from source:
Expand Down Expand Up @@ -93,55 +96,29 @@ async with WillowClient("http://localhost:3031") as client:

### DID Operations

Willow DIDs are **self-certifying**: the id is derived from the public key, not
chosen. The derivation is:

```
did = "did:willow:z" + base58btc( SHA3-256( multicodec_prefix || public_key ) )
```

where `multicodec_prefix` is `0xED 0x01` for Ed25519 and `0xE7 0x01` for
secp256k1 (hashing the 33-byte compressed key), and the leading `z` is the
multibase base58btc marker. The chain's `RegisterDid` check recomputes this and
rejects any other id.

```python
from willow import generate_did, derive_did
from willow import generate_did

# Ed25519 (default)
did_info = generate_did()

# secp256k1 (Ethereum-compatible)
did_info = generate_did(algorithm="secp256k1")

# Derive the DID for an existing public key (hex or bytes) without a keypair:
derived = derive_did("a003201e65e47d578ad9bb17cb1d3590e9f504f55eac6ee40002e3ab9517c49c")
# -> {"did": "did:willow:zDZ1Qqspppayjd9LF3Pkebq64Fa2PuK8zFQDDc11citB2", ...}
await client.register_did(did_info["did_document"])

# did_info keys: did, private_key, public_key, public_key_id, did_document, algorithm
```

#### Onboarding: pre-fund, then register

Because the id is bound to the key, it is known *before* registration and must
be funded first:

```python
# 1. Pre-fund: a funded account sends >= the registration fee to the derived id.
# (e.g. via the consensus client's transfer)
# 2. Register: the holder registers; the fee is paid from that balance.
await client.register_did(did_info["did_document"])
```

### Authentication (per-request signing)

There is no server-side session. Each authenticated request is signed locally with the identity you set via `client.set_identity(...)`. The call is synchronous.

```python
client.set_identity(
did=did_info["did"],
private_key_hex=did_info["private_key"],
public_key_id=did_info["public_key_id"],
did="did:willow:ed25519:abc123",
private_key_hex="your_private_key_hex",
public_key_id="did:willow:ed25519:abc123#key-1",
)

if client.is_authenticated():
Expand Down
Loading