Verifiable Storage

Prove that every ROS 2 data point came from the right robot.

The storage bridge turns raw telemetry into signed, auditable records. When require_did is enabled, the bridge checks once at startup that the robot’s DID exists on chain. Each ingest payload is then hashed and signed, the data and a signature envelope go to IPFS, and the envelope CID is written on chain.

Architecture

Stage	What Happens	Verification Hooks
1. Ingest	StorageIngest message arrives on peaq/storage/ingest	Bridge uses the robot wallet and DID it loaded at startup (the on-chain DID check with require_did runs once, at startup)
2. Encode	Payload hashed with SHA-256; the robot key signs sha256("<dataSha256>|<createdAt>|<robotId>") (sr25519); data and envelope uploaded to IPFS	The envelope (peaq-ipfs-envelope@v1) records dataCid, dataSha256, the public key, and the signature
3. Submit	Envelope CID sent to the storage pallet through the core node	Transaction is signed by the robot’s keystore; peaq/tx_status reports PENDING for the submission
4. Finalize	On-chain record holds {"envelopeCid": "<cid>"}	Any consumer can fetch the envelope, fetch the data CID, recompute the hash, and check the signature

Launch the Bridge

ros2 run peaq_ros2_core storage_bridge_node --ros-args \
  -p config.yaml_path:=/work/peaq_ros2_examples/config/peaq_robot.yaml

Verification-Centric Configuration

storage_bridge:
  robot:
    require_did: true            # verify robot DID is registered on peaq
  storage:
    mode: pinata                 # local_ipfs | pinata | both (both behaves like pinata)
    pinata:
      jwt: "<PINATA_JWT>"        # Pinata JWT
      gateway_url: "https://your-gateway.mypinata.cloud/ipfs"
      pin: true                  # pin: true and mode: upload are both needed to upload to Pinata
      mode: upload

signature:
  algorithm: sr25519             # bridge signs payloads with the robot wallet

A failed blockchain submission of an uploaded IPFS envelope is retried twice, five seconds apart, then written to the failure log. If the core node’s storage/add service is unreachable, the bridge reports FAILED right away and does not retry or log the envelope, so keep the core node active while the bridge runs. IPFS upload and signing failures are reported on peaq/storage/status but are not written to that log. Secrets for managed gateways (JWT or API keys) and wallet passwords must stay out of source control, so load them from environment variables before launch.

IPFS Setup

Local IPFS (Kubo)

# Install Kubo (linux-amd64 build; on ARM use kubo_v0.38.1_linux-arm64.tar.gz)
wget https://dist.ipfs.tech/kubo/v0.38.1/kubo_v0.38.1_linux-amd64.tar.gz
tar -xzf kubo_v0.38.1_linux-amd64.tar.gz
sudo bash kubo/install.sh

# Initialize and start
ipfs init
ipfs daemon

Update the config YAML to point at your node:

storage_bridge:
  storage:
    mode: local_ipfs
    local_ipfs:
      api_url: http://127.0.0.1:5001
      gateway_url: http://127.0.0.1:8080/ipfs

Set local_ipfs.save_dir to cache uploaded artifacts on the robot.

Managed Gateway (Optional)

Use a third-party IPFS pinning or gateway provider only if you need off-device persistence or public access. Pinata is the supported managed upload provider. The bridge uploads to the Pinata API only when the pinata block sets both pin: true and mode: upload; with mode: pinata alone, artifacts go to the local IPFS node. gateway_url only sets the gateway the bridge reports for reading artifacts back, so it can point at any compatible read gateway.

The bridge parses the config with yaml.safe_load and does no environment expansion, so a ${VAR} placeholder is sent verbatim as the bearer token. Put the real values in the YAML and keep the file out of git:

storage_bridge:
  storage:
    mode: pinata
    pinata:
      jwt: "<your Pinata JWT>"
      gateway_url: "https://your-gateway.example.com/ipfs"
      pin: true
      mode: upload

To keep secrets out of the checked-in config, store the placeholders in a template and render it before launch:

export PEAQ_ROBOT_IPFS_JWT="<your Pinata JWT>"
export PEAQ_ROBOT_IPFS_GATEWAY="https://your-gateway.example.com/ipfs"
envsubst < config.template.yaml > config.yaml

both currently behaves the same as pinata; the bridge writes each artifact to one backend only.

Wallets

The wallet referenced in wallet.path needs enough balance on the target network to pay for the storage transaction. Fund it from the faucet on agung.

Publishing Verifiable Data

ros2 topic pub --once /peaq/storage/ingest \
  peaq_ros2_interfaces/msg/StorageIngest \
  '{key: "robot:telemetry", content: "{\"battery\": 0.87}", is_file: false}'

ros2 topic echo /peaq/storage/status

The status stream carries the envelope CID, its gateway URL, the transaction hash, and the current status for each submission. Use it for the outcome of a storage write: peaq/tx_status publishes PENDING only.

Reading & Verifying Downstream

ros2 service call /peaq_core_node/storage/read \
  peaq_ros2_interfaces/srv/StoreReadData \
  '{key: "robot:telemetry"}'

The response returns value_json, which holds the envelope CID stored on chain.

Manual Verification Checklist

1. Fetch the envelope CID from the service response.
2. Retrieve the envelope: ipfs cat <CID> or curl <gateway>/<CID>.
3. Fetch the raw data at payload.dataCid and check its SHA-256 against payload.dataSha256.
4. Rebuild the challenge "<payload.dataSha256>|<header.createdAt>|<header.robotId>" (UTF-8). If proof.algorithm is sr25519, verify proof.signatureHex over the raw 32-byte SHA-256 digest of the challenge; if it is ed25519, verify it over the challenge bytes. Use proof.publicKeyHex as the key, and confirm DID ownership using /peaq_core_node/identity/read.

Automated Attestation

• Attach mission metadata via the metadata_json field in StorageIngest so every record includes firmware versions or profile IDs.
• Access control roles live on chain and do not gate the storage bridge. The ROS access services only create and assign roles, so read them back with sdk.access.read_role() in the Robotics Python SDK or with a chain query.
• Use /tmp/storage_bridge_failures.jsonl and the replay scripts to inspect and retry the failed blockchain submissions recorded there. The log does not include IPFS upload or signing failures.

python3 scripts/check_storage_failures.py --details
python3 scripts/retry_failed_storage.py --key robot:telemetry

Observability & Audit

• Switch the core node to JSON logs (PEAQ_ROBOT_LOG_FORMAT=json) for ingestion into SIEM or compliance tooling; the storage bridge logs through the standard ROS logger.
• Track wallet-derived DID and CID pairs in your log pipeline to detect impersonation attempts.

Dashboard Pointers

• peaq/storage/status: success vs failure counts
• /tmp/storage_bridge_failures.jsonl: monitor size and age to detect backlogs
• peaq/tx_status: PENDING notifications for submitted transactions

Continue with Event Streams to observe transaction submissions and messages published by ROS nodes. Confirm transaction inclusion separately with a chain query or Subscan.