SetNet.ProofOfWork 1.1.0

<p align="center"> <img src="https://raw.githubusercontent.com/Povstalez/SetNet/master/assets/icon.png" alt="SetNet" width="96"> </p>

SetNet.ProofOfWork

Hashcash admission gate for SetNet — make mass/bot connections expensive.

On connect the server issues a random challenge; until the client sends a nonce whose SHA-256(challenge ‖ nonce) has enough leading zero bits, the server drops all of that peer's application frames. A single honest client burns a fraction of a second of CPU once; an attacker opening thousands of connections must pay that cost thousands of times. The client side solves and submits automatically. Added by composition — the server gate is chained onto any existing InboundAuthorizer.

Install

dotnet add package SetNet
dotnet add package SetNet.ProofOfWork

Usage

Call ProofOfWorkRuntime.Enable() once at startup (before handler discovery) on both ends so the handshake handlers are registered.

Server:

ProofOfWorkRuntime.Enable();

var server = new MyServer(config);
server.UseProofOfWork(difficulty: 20);   // required leading zero bits (~2^20 hashes)
await server.StartAsync();

Client:

ProofOfWorkRuntime.Enable();

var client = new MyClient(config);
client.UseProofOfWork();                  // auto-solves the challenge on connect
await client.ConnectAsync();

That's it — the client solves the challenge off the receive thread and submits the nonce; once verified, its frames flow normally.

API

Difficulty is the number of required leading zero bits. Cost is roughly 2^difficulty SHA-256 hashes:

Pick the highest value your slowest legitimate client tolerates.

Notes

• Reserved wire types 65506 / 65507. Don't reuse them for application messages.
• Standalone admission gate. PoW blocks all non-PoW frames until solved. If you also use another "deny-until" gate that blocks its own control frames (e.g. SetNet.Auth), run PoW as the connection-admission step and let auth happen after — stacking two mutually-blocking gates can deadlock. SetNet.RateLimit and SetNet.BanList chain fine.
• Mitigation, not authentication. PoW raises the cost of connection floods; it does not identify users. Combine with auth for identity and with rate limiting for sustained abuse.
• One client per process is the common case and fully supported; the challenge is solved and answered on the connection that received it.

Documentation & source

• 🐙 https://github.com/Povstalez/SetNet — full module catalog in docs/MODULES.md

License

MIT