web3-storage · yusefnapora · Oct 31, 2022 · Oct 31, 2022 · Oct 31, 2022 · Oct 31, 2022
@@ -2,22 +2,30 @@ import { useRouter } from 'next/router';
 
 import Link from '../../../components/link/link';
 import NavData from '../../../pages/docs/nav.json';
+import NavDataV2 from '../../../pages/docs/v2/nav.json';
 
 export default function Sidebar({ openMenu }) {
   const router = useRouter();
 
+  const isV2 = router.pathname.includes("/v2")
+  const data = isV2
+    ? NavDataV2
+    : NavData
+
+  const basePath = isV2 ? "/docs/v2" : "/docs"
+
   return (
     <aside className="sidebar">
       <div className="sidebar-wrapper">
-        {NavData.map((primary, idx) => (
+        {data.map((primary, idx) => (
           <div key={`primary-${idx}`} className={primary.name === '' ? 'no-heading' : ''}>
             {primary.name && <h3>{primary.name}</h3>}
             {primary.menu.map((secondary, idx) => (
               <Link
                 onClick={openMenu ? () => openMenu(false) : undefined}
-                className={router.pathname === `/docs/${secondary.src}` ? 'active' : ''}
+                className={router.pathname === `${basePath}/${secondary.src}` ? 'active' : ''}
                 key={`secondary-${idx}`}
-                href={`/docs/${secondary.src}`}
+                href={`${basePath}/${secondary.src}`}
               >
                 {secondary.name}
               </Link>

@@ -8,6 +8,7 @@ const dirName = path.resolve(__dirname);
 const nextra = require('nextra');
 
 const docsPages = require('./pages/docs/nav.json');
+const docsV2Pages = require('./pages/docs/v2/nav.json');
 
 const withNextra = nextra('./modules/docs-theme/index.js');
 
@@ -59,6 +60,7 @@ const nextConfig = {
     const paths = {
       '/ipfs-404.html': { page: '/404' },
       '/docs/': { page: '/docs/intro', statusCode: 301 },
+      '/docs/v2': { page: '/docs/v2/intro', statusCode: 301 }
     };
     // we have to specify the doc paths here to avoid 404 on reload
     docsPages.map(item => {
@@ -68,6 +70,14 @@ const nextConfig = {
         };
       });
     });
+    // again for v2...
+    docsV2Pages.map(item => {
+      item.menu.map(t => {
+        paths[`/docs/v2/${t.src}`] = {
+          page: `/docs/v2/${t.src}`,
+        };
+      });
+    });
     return paths;
   },
 };

@@ -0,0 +1,16 @@
+---
+title: Help & support
+description: Get help using or building with the web3.storage service.
+---
+
+# Get help or support
+
+web3.storage is easy to use and integrate into your developer workflow, but we could all use a little help now and then. If you're having trouble getting started with or using web3.storage, or just want to get advice and support from a global community of deccentralized web builders, here's where to start.
+
+## Questions and community discussion
+
+Have a question about using web3.storage? Want to discuss problems, opportunities, or ideas for integrating web3.storage into your project or product? Join your peers in the developer community in the **#web3-storage** channel on [Discord](https://discord.gg/4zEkFVqwms) or [Slack.](https://filecoin.io/slack)
+
+## Bug reports or feature requests
+
+Found a bug, or have a feature request for how to make web3.storage better? [File an issue](https://github.com/web3-storage/web3.storage/issues/new/choose) and make your voice heard.
@@ -0,0 +1,42 @@
+---
+title: Web3.Storage APIs compared
+description: Learn about the differences between our new API and our original APIs to decide which is the best fit for your use cases.
+---
+
+# Intro
+
+Set the context:
+
+- We have new APIs for content upload and management
+  - Not yet 100% sure what the "marketing names" for the versions are... while drafting, we'll call the new shit "v2" and the old jam "v1".
+- The new APIs use a new auth system with fun new acronyms (UCAN, DIDs, etc).
+  - Supports new access patterns based on delegation
+- v2 supports larger uploads by uploading directly to cloud storage, skipping CF worker bottleneck
+
+Commonalities:
+
+- Both APIs write into Elastic IPFS
+
+  - v2 writes directly to cloud bucket, while v1 goes through an intermediate CF worker
+
+- Both APIs require payment (after free resources are exhausted) & have the same pricing
+  - Caveat: w3up is free during beta, but content stored during beta will need to be paid for eventually
+
+Differences:
+
+- Auth & accounts
+
+  - v1 uses API tokens for auth, after registration via "magic link" or OAuth (GitHub).
+  - v2 uses UCAN tokens generated by the client - access is granted after email registration of client's DID
+    - once an account is registered, client can delegate to other UCAN agents
+
+- Upload mechanics
+
+  - v1 uploads to CloudFlare Workers, which then feed into the "storage backend"
+    - imposes a 100MiB max upload limit per request
+  - v2 uploads directly to cloud storage, using signed upload URLs provided by w3up service
+    - has ~ 4GB per-request limit (I think... need to double check)
+
+- HTTP API
+  - v2 does not expose an HTTP API for end users yet
+    - Must use JS client lib or CLI
@@ -0,0 +1,58 @@
+---
+title: Content addressing
+description: A conceptual overview of content-based addressing for storing and locating files on a decentralized network with web3.storage.
+---
+
+# Content addressing in brief
+
+web3.storage's decentralized file storage relies on _content addressing_ to find, reference, and retrieve your files on the network. Content addressing is a technique for organizing and locating data in a system in which **the key used to locate content is derived from the content itself, rather than its location.** While you don't need to understand content addressing to be able to incorporate web3.storage in your apps and services, if you're curious about what's going on under the hood, read on.
+
+## The basic problem
+
+Consider what happens when you resolve a link like `web3.storage/docs/concepts/content-addressing`. First, your operating system queries a global shared key-value store, split into many domains — you may know this as the Domain Name System (DNS). The DNS returns an IP address that your network card can use to send HTTP requests over the network, where this site's naming conventions turn the key `/concepts/content-addressing` into a response payload.
+
+The problem is, components of an address like `web3.storage/docs/concepts/content-addressing` are _mutable_, meaning they can change over time. In the context of the web, where _everything_ is mutable and dynamic, this is just the way it's always been. As a result, [link rot](https://en.wikipedia-on-ipfs.org/wiki/Link_rot) is just something we've all learned to live with.
+
+## CIDs: Location-independent, globally unique keys
+
+However, thanks to content addressing, link rot may become a thing of the past. A content-addressed system such as web3.storage is like our key-value-based DNS, with one significant difference: You no longer get to choose the keys. Instead, the keys are derived directly from the file contents using an algorithm that will always generate the same key for the same content.
+
+As a result, we no longer need to coordinate among multiple writers to our store by splitting the key space into domains and locations on file systems. There's now one universal domain: the domain of all possible values. If multiple people add the same value, there's no collision in the key space. They just each get the same key back from the `put` method, with one additional benefit: The availability and performance of retrievals on the network is increased. This gives our keys _location independence_. There's one other important result: Each individual key is a unique signature for the data itself, ensuring _verifiability_ that the key matches the content and the content hasn't been altered.
+
+This type of key is called a _content identifier (CID)_. Once you know the CID of a file on the web3.storage network, you have all you need for the network to locate and return the file back to you. Here's a JavaScript example of a complete storage and retrieval round trip using web3.storage:
+
+```javascript
+// get uploaded files from a form
+const fileInput = document.querySelector('input[type="file"]');
+
+// store files and obtain a CID
+const rootCid = await client.put(fileInput.files);
+
+// retrieve files using the CID
+const res = await client.get(rootCid);
+const files = await res.files();
+for (const file of files) {
+  console.log(`${file.cid} ${file.name} ${file.size}`);
+}
+```
+
+## web3.storage CIDs under the hood
+
+web3.storage uses CIDs to make its free, decentralized file storage work, with help from [IPFS](https://ipfs.io) and [Filecoin](https://filecoin.io/) for locating files and making sure they're always available.
+
+Content addressing is the basis of the peer-to-peer hypermedia protocol IPFS (the InterPlanetary File System), which web3.storage uses to locate files. When web3.storage stores your data on IPFS, it can be retrieved from any IPFS node that has a copy of that data. This can make data transfers more efficient and reduce the load on any single node. As each user fetches a piece of data, they keep a local copy around to help other users who might request it later.
+
+In addition to web3.storage making it easy to get your data onto the content-addressed IPFS network, it also provides long-term persistence for your files using the decentralized Filecoin storage network. The Filecoin network incentivizes participants to provide storage space for files on the network — for more details, see the [concept guide to decentralized storage](/docs/concepts/decentralized-storage/). **By combining IPFS and Filecoin storage into one easy-to-use service, web3.storage makes it simple to store, locate, and retrieve your files on the decentralized web.**
+
+## Summary
+
+Using content addressing for locating files rather than the legacy web's method of location-dependent addressing responds to several critical weaknesses of the legacy web:
+
+- Content addressing solves for the problem behind link rot — the mutability of location-dependent storage systems — by using a hashing algorithm to generate a unique CID for each file that can be used as the lookup key for a file rather than a URL.
+- In addition to making sure files don't get lost if they're moved, content addressing also ensures that users intending to retrieve a specific version of a file will be guaranteed to retrieve that version for as long as it exists anywhere on the network.
+
+## Learn more
+
+Want a deep dive into content addressing, how it works, and why it's important? Check out [ProtoSchool](https://proto.school/content-addressing/) for an in-depth look at content addressing on the decentralized web, plus a wealth of other interactive tutorials on DWeb concepts, protocols, and tools.
+
+Want a technical explanation of how IPFS CIDs work in particular? Have a look at the [official IPFS docs](https://docs.ipfs.io/concepts/content-addressing/).
@@ -0,0 +1,73 @@
+---
+title: Decentralized storage
+description: Learn about decentralized storage works and how it's key to web3.storage.
+---
+
+# Decentralized storage in brief
+
+web3.storage relies on _decentralized storage_ to store your files for free on the network. **Decentralized storage is a technique for storing data that, instead of traditional servers, uses a distributed network with many participants providing storage capacity.** This model inherently builds in redundancy that provides resilience against failure and attacks, as well as enhanced performance due to the geographical localization offered by a large network of distributed storage providers. While you don't need to understand decentralized storage to be able to incorporate web3.storage in your apps and services, if you're curious about what's going on under the hood, read on.
+
+## Content persistence
+
+Broadly speaking, much of today's web operates using what is known as _location addressing_. Location addressing retrieves online information from specific locations on the web ─ i.e. from behind URLs.
+
+```
+https://example.com/page-one.html
+```
+
+However, this approach has some critical problems. Location addressing is _centralized_, meaning that **whoever controls that location controls the content**. The controller can change the content, completely replace it, or just take it away. This means location-based addresses are vulnerable to attacks, exploitation, and loss.
+
+One part of an approach to _decentralizing_ this legacy way of operating the web entails implementing a new kind of addressing: [_content addressing_](/docs/concepts/content-addressing). Content addressing is the technique of issuing each piece of data a _content identifier (CID)_, which is a token derived directly from the file's contents using an algorithm that will always generate the same key for the same content. Using content addressing, files can be queried and retrieved based on _what they are_, not _where they are_ — one major ingredient in enabling the web to break free from centralized content control. However, content addressing is only part of the solution.
+
+web3.storage uses CIDs generated by [IPFS](https://ipfs.io), the InterPlanetary File System, to enable content addressing for all data stored in its network — however, **just because a file has a CID doesn't mean that the file is guaranteed to be around forever**. In a well-operating decentralized system, participants all need to agree to be good actors and provide reliable storage capacity. For this, web3.storage uses the [Filecoin](https://filecoin.io) network. The Filecoin network and its namesake token FIL (or ⨎ for short) were created to incentivize storage providers on the network to agree to _storage deals_. These deals specify that a certain amount of storage capacity will be provided over an agreed period of time, ensuring the second part of the solution: _content persistence_.
+
+## Filecoin for verifiable content persistence
+
+Leveraging the Filecoin network for data stored using web3.storage ensures that content is available for retrieval, thus assuring that the content-based addressing provided by IPFS remains resilient over time. Filecoin achieves this mission using a number of methods, including [novel cryptography, consensus protocols, and game-theoretic incentives](https://filecoin.io/blog/posts/filecoin-features-verifiable-storage/) — but perhaps the most important of these is Filecoin's unique approach to storage verification.
+
+Filecoin's storage verification system solves a previously intractable problem for decentralized storage: How can storage providers _prove_ that they are really storing the data they say they are over time? Filecoin's [proving algorithms](https://filecoin.io/blog/posts/what-sets-us-apart-filecoin-s-proof-system/) take care of this verification:
+
+- [_Proof-of-Replication_](https://proto.school/verifying-storage-on-filecoin/03) proves that a given storage provider is storing a unique copy of a client's original data.
+- [_Proof-of-Spacetime_](https://proto.school/verifying-storage-on-filecoin/04) proves that the client's data is stored continuously over time.
+
+In addition to this proof system, the Filecoin network also relies on _game-theoretic incentives_ to discourage malicious or negligent activity. In order to become a Filecoin storage provider, all potential providers must provide collateral in the form of FIL when agreeing to a storage deal. Additionally, any storage provider that fails Proof-of-Spacetime checks is penalized, loses a portion of their collateral, and is eventually prevented from offering storage to clients again.
+
+## Storing and monitoring with web3.storage
+
+How can you see these principles in action with your files uploaded to web3.storage? It's easy using the web3.storage [JavaScript client library](/docs/reference/js-client-library).
+
+When you [upload a file to web3.storage](/docs/how-tos/store) using the `put()` method, you get the CID of that file in return. The file is then put into a queue for geographically distributed Filecoin network storage providers who have been chosen for performance and availability. These providers bid on the right to store the files in the queue — including your file — and agree to a storage deal.
+
+You can monitor this activity for files you upload to web3.storage by [calling `status()`](/docs/how-tos/query#querying-for-status-information) and providing a file's CID. This will return a list of deals that have been made at the time of query. Here's how you might include this call in your JavaScript project:
+
+```javascript
+// get files from form object
+const fileInput = document.querySelector('input[type="file"]');
+
+// store files, obtain CID
+const rootCid = await client.put(fileInput.files, {
+  name: 'my files',
+  maxRetries: 3,
+});
+
+// query status based on CID
+const info = await client.status(rootCid);
+
+// display results of query
+console.log(`${info.cid} ${info.dagSize} ${info.created}`);
+for (const deal of info.deals) {
+  console.log(`${deal.id} -- ${deal.status}`);
+}
+```
+
+## Summary
+
+The legacy approach of using location addressing to reference files on the web has a number of critical vulnerabilities to interference, exploitation, and loss. Because whoever controls the location controls the content, these location-addressed, centrally stored networks also leave the web exposed to the whims of big, corporate central storage platforms.
+
+By pairing IPFS content addressing (to decentralize how resources are specified) with Filecoin (to decentralize how storage capacity is obtained), it becomes possible to create a complete solution for locating, storing, and obtaining data — one that is not only resilient against these vulnerabilities, but also rewarding for network participants.
+
+**web3.storage combines the content addressing capabilities of IPFS and the proving algorithms and storage deal marketplace of Filecoin in order to achieve this complete solution**, wrapping the power of these two systems into an easy-to-use service with simple, familiar methods such as [`put()`](/docs/how-tos/store), [`get()`](/docs/how-tos/retrieve), and [`status()`](/docs/how-tos/query). **Even better, web3.storage is free to use and integrate into your apps and services.**
+
+## Learn more
+
+Want a deep dive into decentralized storage, how it works, and why it's important? Check out [ProtoSchool](https://proto.school/verifying-storage-on-filecoin/) for an in-depth look at verifying storage on Filecoin, plus a wealth of other interactive tutorials on DWeb concepts, protocols, and tools.
@@ -0,0 +1,15 @@
+---
+title: DIDs and accounts
+description: Learn about Decentralized Identity Documents (DIDs) and how they relate to web3.storage accounts.
+---
+
+# Intro & context
+
+## What is a DID?
+
+- w3c spec, etc.
+- lots of methods, but we use `did:key:` because it's simple and doesn't need indirection / lookup on a "registry"
+
+## Accounts
+
+## Agents
@@ -0,0 +1,12 @@
+---
+title: Our infrastructure
+description: Learn how web3.storage works behind the scenes
+---
+
+## Intro
+
+## CARs all the way down
+
+## Elastic IPFS
+
+## Gateways & Freeway
@@ -0,0 +1 @@
+> **TODO**: Port intro to UCAN content from https://blog.web3.storage/posts/intro-to-ucan