Merge pull request #3 from hpp-io/1-noosphere-payload

1 noosphere pURI scheme-based payload handlingayload

Author: nolnol3

.github/workflows/ci.yml

@@ -12,7 +12,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [18.x, 20.x]
+        node-version: [20.x, 22.x]
 
     steps:
       - name: Checkout repository
@@ -22,10 +22,9 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
-          cache: 'npm'
 
       - name: Install dependencies
-        run: npm ci
+        run: yarn install --frozen-lockfile || yarn install
 
       - name: Build
         run: npm run build

.gitignore

@@ -1,6 +1,5 @@
 # Dependencies
 node_modules/
-yarn.lock
 
 # Build outputs
 dist/

README.md

@@ -40,7 +40,7 @@ Noosphere SDK enables you to build and run compute agents that participate in th
 npm install @noosphere/sdk
 
 # Or install individual packages
-npm install @noosphere/agent-core @noosphere/crypto @noosphere/contracts @noosphere/registry
+npm install @noosphere/agent-core @noosphere/crypto @noosphere/contracts @noosphere/registry @noosphere/payload
 ```
 
 ### Basic Example
@@ -94,6 +94,14 @@ await agent.start();
 │    ├── EventMonitor      (blockchain events)            │
 │    └── ContainerManager  (Docker execution)             │
 ├─────────────────────────────────────────────────────────┤
+│  @noosphere/payload      (browser & Node.js)            │
+│    ├── PayloadResolver   (URI-based payload handling)   │
+│    └── Storage providers                                │
+│         ├── IpfsStorage    (IPFS/Pinata)                │
+│         ├── S3Storage      (S3/R2/MinIO)                │
+│         ├── DataUriStorage (inline data)                │
+│         └── HttpStorage    (HTTP/HTTPS)                 │
+├─────────────────────────────────────────────────────────┤
 │  @noosphere/contracts                                   │
 │    ├── ABIs              (contract interfaces)          │
 │    ├── TypeChain types   (type-safe wrappers)           │
@@ -127,6 +135,32 @@ await agent.start();
 - `EventMonitor` - Blockchain event listener with WebSocket support
 - `ContainerManager` - Docker container execution
 
+### [@noosphere/payload](./packages/payload) · [npm](https://www.npmjs.com/package/@noosphere/payload)
+
+PayloadData utilities for URI-based payload handling. Works in both browser and Node.js environments.
+
+```typescript
+import { PayloadResolver, createDataUriPayload } from '@noosphere/payload';
+
+// Create PayloadData
+const payload = createDataUriPayload('{"action": "ping"}');
+
+// Resolve PayloadData
+const resolver = new PayloadResolver({ ipfs: { gateway: 'https://ipfs.io/ipfs/' } });
+const { content, verified } = await resolver.resolve(payload);
+```
+
+**Key Components:**
+- `PayloadResolver` - Resolves and encodes PayloadData with verification
+- `IpfsStorage` - IPFS/Pinata storage provider
+- `S3Storage` - S3/R2/MinIO storage provider
+- `DataUriStorage` - Inline base64 data URI provider
+
+**Supported URI Schemes:**
+- `data:` - Inline base64-encoded data
+- `ipfs://` - IPFS content addressing
+- `https://` / `http://` - HTTP(S) URLs
+
 ### [@noosphere/contracts](./packages/contracts) · [npm](https://www.npmjs.com/package/@noosphere/contracts)
 
 Type-safe contract interfaces and ABIs.
@@ -205,6 +239,54 @@ if (verifier.requiresProof && verifier.proofService) {
 }
 ```
 
+### Payload Resolution
+
+The SDK includes `PayloadResolver` for handling URI-based payload data with multiple storage backends.
+
+```typescript
+import { PayloadResolver } from '@noosphere/agent-core';
+
+const resolver = new PayloadResolver({
+  // IPFS configuration
+  ipfs: {
+    gateway: 'https://gateway.pinata.cloud/ipfs/',
+    apiEndpoint: 'https://api.pinata.cloud',
+    apiKey: process.env.PINATA_API_KEY,
+    apiSecret: process.env.PINATA_API_SECRET,
+  },
+  // S3-compatible storage (R2, S3, MinIO)
+  s3: {
+    endpoint: process.env.R2_ENDPOINT,
+    accessKeyId: process.env.R2_ACCESS_KEY_ID,
+    secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
+    bucket: process.env.R2_BUCKET,
+    publicUrlBase: process.env.R2_PUBLIC_URL,
+  },
+  // Auto-upload threshold (bytes)
+  uploadThreshold: 1024,
+  // Default storage for large payloads
+  defaultStorage: 's3', // 'ipfs' | 's3' | 'data'
+});
+
+// Resolve PayloadData from various URI schemes
+const { content, verified } = await resolver.resolve(payloadData);
+// Supports: data:, ipfs://, https://, http://
+
+// Encode output (auto-uploads if > threshold)
+const outputPayload = await resolver.encode(outputContent);
+```
+
+**Supported URI Schemes:**
+- `data:` - Inline base64-encoded data
+- `ipfs://` - IPFS content addressing
+- `https://` / `http://` - HTTP(S) URLs
+
+**Storage Backends:**
+- `IpfsStorage` - Pinata IPFS pinning service
+- `S3Storage` - S3-compatible storage (AWS S3, Cloudflare R2, MinIO)
+- `DataUriStorage` - Inline data URI encoding
+- `HttpStorage` - HTTP(S) fetch
+
 ## Usage Examples
 
 ### Running a Compute Agent
@@ -324,6 +406,18 @@ RPC_URL=https://...
 # Optional
 WS_URL=wss://...
 WALLET_FACTORY_ADDRESS=0x...
+
+# Payload Storage (S3/R2)
+R2_ENDPOINT=https://xxx.r2.cloudflarestorage.com
+R2_ACCESS_KEY_ID=your-access-key
+R2_SECRET_ACCESS_KEY=your-secret-key
+R2_BUCKET=your-bucket
+R2_PUBLIC_URL=https://pub-xxx.r2.dev
+
+# Payload Storage (IPFS/Pinata)
+PINATA_API_KEY=your-api-key
+PINATA_API_SECRET=your-api-secret
+IPFS_GATEWAY=https://gateway.pinata.cloud/ipfs/
 ```
 
 ### Keystore Structure

docker/docker-compose.yml

@@ -0,0 +1,40 @@
+# =============================================================================
+# Noosphere SDK - Local Verdaccio Registry
+# =============================================================================
+#
+# Local npm registry for SDK development and testing.
+# Allows publishing @noosphere/* packages locally before pushing to npm.
+#
+# Usage:
+#   # Start Verdaccio
+#   docker compose -f docker/docker-compose.yml up -d
+#
+#   # Publish SDK packages
+#   ./scripts/publish-local.sh
+#
+#   # Stop Verdaccio
+#   docker compose -f docker/docker-compose.yml down
+#
+# Access:
+#   Registry: http://localhost:4873
+#   Web UI: http://localhost:4873 (browser)
+#
+# =============================================================================
+
+services:
+  verdaccio:
+    image: verdaccio/verdaccio:5
+    container_name: noosphere-verdaccio
+    ports:
+      - "4873:4873"
+    volumes:
+      - ./verdaccio/config.yaml:/verdaccio/conf/config.yaml:ro
+      - verdaccio-storage:/verdaccio/storage
+    healthcheck:
+      test: ["CMD", "sh", "-c", "wget -q --spider http://localhost:4873/-/ping || exit 1"]
+      interval: 10s
+      timeout: 5s
+      retries: 3
+
+volumes:
+  verdaccio-storage:

docker/verdaccio/config.yaml

@@ -0,0 +1,51 @@
+# =============================================================================
+# Verdaccio - Local npm Registry Configuration
+# =============================================================================
+#
+# This configuration enables a local npm registry for development/testing.
+# @noosphere/* packages are served locally, all others proxy to npmjs.
+#
+# =============================================================================
+
+storage: /verdaccio/storage
+plugins: /verdaccio/plugins
+
+web:
+  title: Noosphere Local Registry
+  enable: true
+
+auth:
+  htpasswd:
+    file: /verdaccio/storage/htpasswd
+    max_users: 100
+
+uplinks:
+  npmjs:
+    url: https://registry.npmjs.org/
+    cache: true
+
+packages:
+  # @noosphere/* packages - local only, no proxy
+  '@noosphere/*':
+    access: $all
+    publish: $all
+    unpublish: $all
+    # Don't proxy to npmjs - use local only
+
+  # All other packages - proxy to npmjs
+  '**':
+    access: $all
+    publish: $authenticated
+    unpublish: $authenticated
+    proxy: npmjs
+
+# Logging
+logs:
+  - { type: stdout, format: pretty, level: info }
+
+# Listen on all interfaces
+listen:
+  - 0.0.0.0:4873
+
+# Max body size for publishing
+max_body_size: 100mb