Merge pull request #39 from boundless-xyz/docs/gcs-storage-provider

docs: add GCS storage provider, update SDK storage API references

Author: sasha-computer

developers/tooling/sdk.mdx

@@ -89,7 +89,8 @@ let (journal, receipt) = client.fetch_set_inclusion_receipt(request_id, [0u8; 32
 - `OrderStreamClient`: Submit/fetch orders offchain via WebSocket.
 
 ### `storage`
-- Providers: `S3` and `Pinata` for uploading program and input data.
+- Uploaders: `S3`, `GCS`, and `Pinata` for uploading program and input data.
+- Downloaders: `HTTP`, `S3`, `GCS`, and `File` for downloading programs and inputs (auto-selected based on URL scheme).
 
 ### `selector`
 - Utilities for tracking/verifying proof types.
@@ -98,21 +99,25 @@ let (journal, receipt) = client.fetch_set_inclusion_receipt(request_id, [0u8; 32
 
 ```rust
 use boundless_market::{
-  Client,
+  Client, StorageUploaderConfig,
   contracts::{FulfillmentData, RequestId, Requirements, Predicate, Offer},
-  storage::storage_provider_from_env,
   request_builder::OfferParams,
 };
 use alloy::signers::local::PrivateKeySigner;
 use alloy::primitives::U256;
 use std::time::Duration;
 use url::Url;
 
-async fn proof_submission(signer: &PrivateKeySigner, rpc_url: Url) -> anyhow::Result<()> {
+async fn proof_submission(
+    signer: &PrivateKeySigner,
+    rpc_url: Url,
+    storage_config: &StorageUploaderConfig,
+) -> anyhow::Result<()> {
     let client = Client::builder()
         .with_rpc_url(rpc_url)
         .with_private_key(signer.clone())
-        .with_storage_provider(Some(storage_provider_from_env()?))
+        .with_uploader_config(storage_config)
+        .await?
         .build()
         .await?;
 

developers/tutorials/request.mdx

@@ -45,17 +45,17 @@ export RPC_URL="https://..."
 export PRIVATE_KEY="abcdef..."
 ```
 
-#### Storage Provider
+#### Storage Uploader
 
 <Tip>
   For this tutorial, we suggest using a Pinata API key which will upload your program at runtime.
 
-  If you do not want to use an API key, or if you want to use a provider other than Pinata, you can pre-upload you program to a public URL (this could be hosted via Pinata or any other service).
+  If you do not want to use an API key, or if you want to use a provider other than Pinata (e.g. S3 or GCS), you can pre-upload your program to a public URL (this could be hosted via Pinata or any other service).
 
-  To see more information about this option, please read [No Storage Provider](/developers/tutorials/request#no-storage-provider).
+  To see more information about storage options, please read [Storage Providers](/developers/tutorials/request#storage-providers).
 </Tip>
 
-To make a program, and its inputs, accessible to provers, they need to be hosted at a public URL. We recommend using IPFS for storage, particularly via [Pinata](https://pinata.cloud), as their free tier comfortably covers most Boundless use cases.
+To make a program, and its inputs, accessible to provers, they need to be hosted at a public URL. We recommend using IPFS for storage, particularly via [Pinata](https://pinata.cloud), as their free tier comfortably covers most Boundless use cases. The SDK also supports [S3](/developers/tutorials/request#s3) and [GCS](/developers/tutorials/request#google-cloud-storage-gcs).
 
 Before submitting a request, you'll need to:
 
@@ -73,7 +73,8 @@ export PINATA_JWT="abcdef..."
 let client = Client::builder()
   .with_rpc_url(args.rpc_url)
   .with_private_key(args.private_key)
-  .with_storage_provider(Some(storage_provider_from_env()?))
+  .with_uploader_config(&args.storage_config)
+  .await?
   .build()
   .await?;
 ```
@@ -111,50 +112,76 @@ This will store the `journal` and `seal` from the Boundless market, together the
 
 ### Storage Providers
 
-The Boundless Market SDK automatically configures the storage provider based on environment variables; it supports both IPFS and S3 for uploading programs and inputs.
+The Boundless Market SDK supports multiple storage backends for uploading programs and inputs: **IPFS (Pinata)**, **S3**, and **Google Cloud Storage (GCS)**. The SDK uses `StorageUploaderConfig` with clap, so the storage backend is configured via environment variables or CLI flags.
 
-#### IPFS
+#### IPFS (Pinata)
 
-For example, if you set the following:
+To use Pinata for IPFS uploads, set the following environment variable:
 
 ```bash
-export PINATA_JWT="abcdef"...
-```
-
-then when you use `.with_storage_provider()`:
-
-```rust
-let client = Client::builder()
-  .with_rpc_url(args.rpc_url)
-  .with_private_key(args.private_key)
-  .with_storage_provider(Some(storage_provider_from_env()?)) // [!code hl] // [!code focus]
-  .build()
-  .await?;
+export PINATA_JWT="abcdef..."
 ```
 
-_IPFS_ is set automatically to the storage provider, and your JWT will be used to upload programs/inputs via Pinata's gateway.
+The SDK picks the storage backend based on which env vars are set. When `PINATA_JWT` is set, it uses Pinata to upload programs and inputs to IPFS.
 
 #### S3
 
-To use S3 as your storage provider, you need to set the following environment variables:
+To use S3 as your storage backend, set the following environment variables:
 
 ```bash
-export S3_ACCESS_KEY="abcdef..."
-export S3_SECRET_KEY="abcdef..."
-export S3_BUCKET="bucket-name..."
-export S3_URL="https://bucket-url..."
-export AWS_REGION="us-east-1"
+export S3_BUCKET="bucket-name"
+export S3_URL="https://s3.us-east-1.amazonaws.com"  # optional, for S3-compatible services
+export AWS_ACCESS_KEY_ID="abcdef..."                 # optional, uses AWS default credential chain if not set
+export AWS_SECRET_ACCESS_KEY="abcdef..."             # optional, uses AWS default credential chain if not set
+export AWS_REGION="us-east-1"                        # optional, can be inferred from environment
 ```
 
 Once these are set, this will automatically use the specified [AWS S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-buckets-s3.html) for storage of programs and inputs.
 
 <Warning>
-  The SDK generates S3 presigned URLs that expire after 12 hours. If your request takes longer to fulfill, provers cannot download your program or inputs after expiry. For long-running requests, use IPFS storage or set `S3_NO_PRESIGNED=1` to use direct S3 URLs with appropriate bucket policies.
+  By default, the SDK generates S3 presigned URLs that expire after 12 hours. If your request takes longer to fulfill, provers cannot download your program or inputs after expiry. For long-running requests, you have a few options:
+
+  - Use IPFS storage instead
+  - Set `S3_PUBLIC_URL=true` to return public HTTPS URLs (requires a public bucket)
+  - Set `S3_PRESIGNED=false` to use direct S3 URLs with appropriate bucket policies
 </Warning>
 
+#### Google Cloud Storage (GCS)
+
+<Note>
+  GCS support requires the `gcs` feature flag: `cargo add boundless-market --features gcs`
+</Note>
+
+To use Google Cloud Storage, set the following environment variables:
+
+```bash
+export GCS_BUCKET="your-bucket-name"
+```
+
+**Authentication** is resolved via the [Google Cloud Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/application-default-credentials) chain:
+
+1. `GOOGLE_APPLICATION_CREDENTIALS` environment variable pointing to a service account JSON key file
+2. Well-known file locations (`~/.config/gcloud/application_default_credentials.json`, set up via `gcloud auth application-default login`)
+3. Workload Identity on GKE, metadata server on Compute Engine, etc.
+
+You can also provide credentials directly via `GCS_CREDENTIALS_JSON` when loading from a secrets manager without writing to disk.
+
+**Configuration:**
+
+| Environment Variable | Description |
+|---|---|
+| `GCS_BUCKET` | **(Required)** GCS bucket name |
+| `GCS_URL` | Custom endpoint URL (for emulators like `fake-gcs-server`) |
+| `GCS_CREDENTIALS_JSON` | Service account JSON string (bypasses ADC) |
+| `GCS_PUBLIC_URL` | Set to `true` to return public HTTPS URLs (`https://storage.googleapis.com/{bucket}/{key}`) instead of `gs://` URLs. Requires the bucket to be publicly readable. |
+
+<Tip>
+  For public buckets, set `GCS_PUBLIC_URL=true` so provers can download via standard HTTPS without needing GCS credentials. After each upload, a HEAD request verifies the object is publicly accessible.
+</Tip>
+
 #### No Storage Provider
 
-A perfectly valid option for `StorageProvider` is `None`; if you don't set any relevant environment variables for IPFS/S3, it won't use a storage provider to upload programs or inputs at runtime. This means you will need to upload your program ahead of time, and provide the public URL. For the inputs, you can also pass them inline (i.e. in the transaction) if they are small enough. Otherwise, you can upload inputs ahead of time as well.
+If you don't set any storage-related environment variables, no storage backend is configured. This means you will need to upload your program ahead of time, and provide the public URL. For the inputs, you can also pass them inline (i.e. in the transaction) if they are small enough. Otherwise, you can upload inputs ahead of time as well.
 
 ### Uploading Programs
 
@@ -164,7 +191,8 @@ Provers must be able to access your guest program via a publicly accessible URL;
 
 ```rust
 let client = Client::builder()
-  .with_storage_provider(Some(storage_provider_from_env()?))
+  .with_uploader_config(&args.storage_config)
+  .await?
   .build()
   .await?;
 let program_url = client.upload_program(program).await?;
@@ -380,7 +408,8 @@ Use `config_offer_layer` when you want to adjust how the SDK calculates auction
 let client = Client::builder()
   .with_rpc_url(args.rpc_url)
   .with_private_key(args.private_key)
-  .with_storage_provider(Some(storage_provider_from_env()?))
+  .with_uploader_config(&args.storage_config)
+  .await?
   .config_offer_layer(|config| config
     // Set the price per cycle for automatic pricing calculations
     .max_price_per_cycle(parse_units("0.1", "gwei").unwrap())
@@ -417,7 +446,8 @@ The funding mode can be configured when building the client using `with_funding_
 let client = Client::builder()
   .with_rpc_url(args.rpc_url)
   .with_private_key(args.private_key)
-  .with_storage_provider(Some(storage_provider_from_env()?))
+  .with_uploader_config(&args.storage_config)
+  .await?
   .with_funding_mode(FundingMode::Always) // [!code hl] // [!code focus]
   .build()
   .await?;

developers/tutorials/sensitive-inputs.mdx

@@ -199,12 +199,12 @@ With your inputs now sitting privately in S3, you may now [request a proof](/dev
 If you have already uploaded your inputs using the `aws` CLI above, you can skip the information below. Otherwise, if you are interested in using the Boundless SDK to upload your inputs to your S3 bucket, you will need to:
 
 - make sure your AWS credentials are set in environment variables, specifically:
-  - `S3_ACCESS` for the access key
-  - `S3_SECRET` for the secret key
+  - `AWS_ACCESS_KEY_ID` for the access key (optional if using the AWS default credential chain)
+  - `AWS_SECRET_ACCESS_KEY` for the secret key (optional if using the AWS default credential chain)
   - `S3_BUCKET` for the bucket name of the bucket created in [Create the S3 bucket](/developers/tutorials/sensitive-inputs#1-create-the-s3-bucket)
-  - `S3_URL` for the bucket URL of the bucket created in [Create the S3 bucket](/developers/tutorials/sensitive-inputs#1-create-the-s3-bucket)
-  - `AWS_REGION` for the bucket region.
-  - and last, but not least, make sure `S3_NO_PRESIGNED=1`
+  - `S3_URL` for the bucket endpoint URL of the bucket created in [Create the S3 bucket](/developers/tutorials/sensitive-inputs#1-create-the-s3-bucket)
+  - `AWS_REGION` for the bucket region
+  - and last, but not least, make sure `S3_PRESIGNED=false` to use direct S3 URLs
 
 After this setup, you may request a proof programmatically as [Request a Proof](/developers/tutorials/request) recommends; your inputs will be automatically uploaded to your gated S3 bucket, however remember that you still need to go through all the necessary gating policies as laid out in this tutorial to make sure your inputs are private and only available to select provers.
 
@@ -213,7 +213,7 @@ If you're interested in doing a one-off test, take a look at the [requestor modu
 
 <Check>
 Relevant Links:
-[StorageProvider](https://docs.rs/boundless-market/latest/boundless_market/storage/trait.StorageProvider.html), [storage_provider_from_env](https://docs.rs/boundless-market/latest/boundless_market/storage/fn.storage_provider_from_env.html).
+[StorageUploader](https://docs.rs/boundless-market/latest/boundless_market/storage/trait.StorageUploader.html), [StorageUploaderConfig](https://docs.rs/boundless-market/latest/boundless_market/storage/struct.StorageUploaderConfig.html).
 </Check>
 
 ## Prover