what do you think about a : Freenet Universal API Proxy (FUAP)

[guidryheal-create]

A Generalized Contract-Based Protocol Bridge for HTTP, MCP, and Beyond

---

1. Goal (what we are actually building)

Create a general-purpose Freenet contract that acts as a protocol-neutral request/response broker, enabling:

• HTTP-style APIs
• MCP-style agent protocols
• Any request/response protocol

…to be projected onto Freenet, while still feeling like a normal synchronous API to the client, via a local gateway.

The user experience:

Client → http://localhost:PORT/freenet/<contract_id>/api/endpoint

The client believes it is calling a normal API.
Under the hood, the call becomes a Freenet state transition + eventual callback.

---

2. Non-goals (important constraints)

This system does not:

• Tunnel raw TCP or HTTPS
• Preserve HTTP ordering guarantees
• Provide real-time global responses
• Expose secrets or TLS keys to the network
• Allow side effects inside contracts

Instead, it reifies protocols as data.

---

3. High-level architecture

┌─────────────┐
│ HTTP / MCP  │
│   Client    │
└──────┬──────┘
       │
       ▼
┌─────────────────────┐
│ Local API Gateway   │  (FastAPI / ASGI)
│  - Protocol parser  │
│  - Contract router  │
│  - Response waiter  │
└──────┬──────────────┘
       │ WebSocket
       ▼
┌─────────────────────┐
│ Freenet Kernel      │
└──────┬──────────────┘
       │
       ▼
┌─────────────────────┐
│ Delegate (WASM)     │  ← secrets, signing, encryption
└──────┬──────────────┘
       │
       ▼
┌─────────────────────┐
│ Proxy Contract      │  ← protocol-neutral CRDT
│ (replicated)        │
└─────────────────────┘

River already demonstrates:

• Kernel ↔ Delegate ↔ Contract
• UI ↔ Kernel via WebSocket
• State-driven UI updates

We reuse that exact pattern, but the “UI” becomes a local protocol gateway.

---

4. Core idea: protocols as replicated data

Instead of routing traffic, we model requests and responses as state.

Canonical request object

All incoming protocols are normalized into a single structure:

struct ProxyRequest {
    request_id: RequestId,        // deterministic, content-derived
    origin: OriginId,              // client / node / delegate
    protocol: ProtocolKind,        // HTTP | MCP | CUSTOM
    method: String,                // GET, POST, CALL, etc.
    path: String,                  // /api/foo
    headers: BTreeMap<String, String>, // canonicalized subset
    body_hash: Hash,               // content-addressed
    body_ref: Option<BlobRef>,     // optional external payload
    timestamp_bucket: u64,         // coarse time for replay safety
}

Canonical response object

struct ProxyResponse {
    request_id: RequestId,
    status: ResponseStatus,        // OK | ERROR | PENDING
    code: u16,                     // HTTP-like semantics
    headers: BTreeMap<String, String>,
    body_ref: Option<BlobRef>,
}

These are pure data, suitable for a Freenet contract.

---

5. The Proxy Contract (generalized, reusable)

Responsibilities

The proxy contract:

• Stores requests and responses

• Enforces:

  • Idempotency
  • Replay safety
  • Structural validity

• Ensures commutative merges

It does not:

• Execute requests
• Perform IO
• Understand HTTP semantics deeply

Contract state (simplified)

#[composable]
pub struct ProxyState {
    pub requests: Map<RequestId, ProxyRequest>,
    pub responses: Map<RequestId, ProxyResponse>,
    pub tombstones: Set<RequestId>,
}

This state forms a commutative monoid:

• Requests only added
• Responses only added or merged
• Tombstones prevent resurrection

River already uses this pattern for messages and rooms.

---

6. Who executes the request?

This is the crucial inversion.

The network does not execute requests. Peers do.

Execution flow

1. Client sends HTTP request to local gateway

2. Gateway converts it → ProxyRequest

3. Delegate signs and submits it to the contract

4. Any subscribing peer may:

   • Observe the request
   • Decide it is responsible
   • Execute it locally

5. Executor submits a ProxyResponse delta

6. State converges

7. Original client receives the response via subscription

This is work stealing, not client/server.

---

7. How the client still “feels” synchronous

The illusion of a normal API call is maintained locally.

Local gateway behavior

• Accept HTTP request

• Submit request to Freenet

• Block (or async-wait) on:

  • Response appearing in contract state
  • Timeout

• Return HTTP response to client

This is local blocking over global async state.

Exactly how River’s UI waits for message sync—just repurposed.

---

8. Contract address as routing primitive

The URL embeds the contract identity:

http://localhost:8080/freenet/<contract_id>/api/foo

Routing logic:

• <contract_id> → Freenet contract instance
• /api/foo → protocol-level path
• Method → request semantics

This mirrors how River uses:

• Contract ID = room
• Messages = state deltas

---

9. Protocol extensibility (HTTP, MCP, others)

Protocols differ only before normalization and after response materialization.

The proxy contract itself is protocol-agnostic.

Adapters live in the gateway:

Protocol	Adapter role
HTTP	Headers + status mapping
MCP	Tool-call serialization
gRPC	Message framing
Custom	User-defined

This makes the contract stable and reusable.

---

10. Security model

What is trusted

• Local gateway
• Delegate
• Local execution environment

What is not

• Other peers
• Contract code
• Contract state

Guarantees

• Requests are signed
• Responses are attributable
• No secrets ever leave the delegate
• Replay attacks are detectable
• Malicious peers can be ignored

---

11. Why River is the correct foundation

River already proves:

• UI as WASM
• Kernel as broker
• Contract as replicated state
• Delegate as trust boundary
• Eventual-consistency UX

This proxy system is River without chat semantics.

Replace:

• Message → ProxyRequest
• Room → Contract ID
• UI → Local API Gateway

Same architecture. Different payload.

---

12. What this enables (realistically)

• Backendless APIs
• Decentralized MCP tool networks
• Censorship-resistant service meshes
• Offline-first API clients
• Agent-to-agent RPC without servers

Not faster than HTTP.
Not simpler than REST.

But structurally different in a way that scales where servers fail.

---

13. Final framing (this matters)

You are not proxying traffic.

You are projecting protocols onto replicated truth.

Once you see that, the design stops fighting physics and starts cooperating with it.

[guidryheal-create]

Idea would be to bridge any to any and make pythonic or else WSGI totaly ok to freenet protocol that would then just act as a better proxy rather than a long new way to code the internet to the eyes of a dev

[guidryheal-create]

not optimal compare to rewriting everything in rust so i admit it

[iduartgomez]

This can be built as an external extension, I don't think we need native support in the peer for it right? Is just another abstraction on top of the HTTP gateway and the websocket API.

[guidryheal-create]

ho no just asking about it like would you enjoy it ?
is it worth the effort, does it touch more people than just me ?

cause i mean i can just tailscale or zerotrust my own process but it s quite usefull still i feel like

[guidryheal-create]

might make it easier to dev on freenet so as so then any website could just be brodcast to it without complex scheme and contract in rust but rather just one for all. even so i think i get that you wanna type low level request type for a safety reason. no unexpected payload or else