Peepeth is two things: an open-source smart contract running on the Ethereum blockchain (data storage), and Peepeth.com (a front-end). This document explains how they interact and discusses some other moving parts.
Peepeth's smart contract stores all Peepeth data, such as account information and Peep content. Well, it doesn't really store that data per se; rather, it stores a link to that data. The data itself is saved to a decentralized data store called the Interplanetary File System (IPFS).
Why not just store data on the blockchain itself? It's expensive. All blockchain transactions cost gas, a measure of computational / storage requirements. Storing data is particularly expensive. It's much cheaper to just store a link to the data.
Why use the blockchain at all? The blockchain provides a guarantee of who posted something when, and ties together all the data in one location.
Peepeth.com, this website, is a front-end for the Peepeth smart contract. This site reads to and writes from the contract. It also adds other functionality that's impossible to do with only the blockchain, such as email notifications and Twitter cross-posting.
Peepeth.com works a lot like normal web applications. The main difference is that the data store, the smart contract, is open source.
Peepeth.com is centralized. It can be censored and taken down. However, if it does go down, anybody can create another front-end and restore the back-end's incorruptable data.
How does Bulk Posting work?
Peepeth lets you post your actions to the blockchain in bulk. Normally, you'd have to pay Ethereum transaction fees for every Peep or follow, an expensive and slow procedure.
But with Bulk Posting, you can post or follow on Peepeth.com instantly and freely, and then save all outstanding Peeps to the blockchain at your leisure in a single, cheap transaction. This makes it almost free to use Peepeth.
Bulk Posting works by saving a centralized record of your activity on Peepeth.com. When you're ready, Peepeth lets you save all of that data to the blockchain in a single transaction. Currently, you can save up to 15 actions off-chain at a time before having to commit them to the blockchain.
Use this feature when you're posting non-critical Peeps. Other front-ends cannot trust the timestamps of Peeps that are saved in a batch; instead, those front-ends have to assume that all batch-saved Peeps share the same timestamp of the Bulk Posting itself. However, Peepeth.com keeps track of the original timestamps, so batch-saved Peeps still appear in chronological order on Peepeth.com.
You need to sign in to use Bulk Posting. See below.
How does Free Peeping work?
Peepeth makes it even easier to Peep. If you've Peeped at least 50 times and are in good standing after 7 days, you can take most actions (post Peeps, follow, and offer Ensō) for free.
Instead of sending batches of actions to the blockchain, you'll instead cryptographically sign those batches with your Ethereum key, and Peepeth will save them for you.
Free Peeping is a feature provided to Peepers in good standing on the Peepeth.com front-end.
To read more about signing, click here.
You need to sign in to use Free Peeping. See below.
How does Sign In work?
After you create an account, Peepeth will ask you to sign in. A MetaMask window will pop up, and you'll be asked to click "Sign". Why?
Peepeth has some convenience features (bulk posting, email notifications, Twitter cross-posting) that require you to prove to us that you own your Ethereum address. That's what signing in does.
"But I just created an account, isn't that proof that I own my Ethereum address?" When you create an account, you're saving data to the blockchain, and the smart contract knows for sure that you control your Ethereum address. However, Peepeth.com has no guarantee that you (the current user of Peepeth.com) actually own that address. When you sign in to Peepeth.com's servers, you are sending proof that you control that address, and then Peepeth.com can manage a server-based account that represents your blockchain account. That lets us manage notifications for you, Tweet your Peeps when you enable it, and let you bulk-save actions to the blockchain.
Signing in does not let Peepeth execute blockchain transactions on your behalf. It only proves to us that you control your Ethereum address. To read more about MetaMask's "sign" feature, click here.
Basically, when you sign in for the first time, you're creating a regular server-based account on Peepeth.com's servers. Instead of sending an email/password combo like most sites require, Peepeth has you send proof of ownership of your Ethereum address.
How does Social Verification work?
Social verification lets you prove your real-world identity through the blockchain. Peepeth has another smart contract that uses an oracle to see if you own social media accounts you claim you own.
To verify a social media account, you'll first post a certain message containing your Ethereum address to a given social media account. Peepeth will then ask you to send the link to that social media post to our smart contract, which will verify that it contains the special message. If it does, the smart contract will mark your social media account as linked to your Ethereum address, and other users will see that you control those external accounts.
How does Twitter cross-posting work?
You can post your Peeps to Twitter after authenticating. You can toggle this option for every Peep you post.