Forem: Paul Berg

How to Code Your Own Confidential Token on Ethereum

Paul Berg — Sat, 16 Feb 2019 11:25:01 +0000

Context

Ethereum is not private. Every time you transfer an ERC20 token or any other digital asset, information is leaked to third parties. They could find out your full financial history simply by heading to Etherscan, Blockscout or any other blockchain explorer out there.

Fear not, there are ways to prevent this. For one, you could use multiple accounts, but you'd have to constantly remember not to cross-link these accounts. This would be a life admin nightmare. What if there was a more elegant and programmable way?

Let me introduce AZTEC: a privacy protocol built on top of Ethereum. In this article, I will not emphasise on the cryptography underpinning the protocol, but rather on its practical applications such as developing confidential tokens.

Disclaimer: I'm working at AZTEC as a full-time software engineer.

Prerequisites

I will further assume that you have a basic understanding of:

Ethereum development using the Truffle Framework
Zero-knowledge proofs
Cryptography and elliptic curves

Make sure you have node.js and npm on your machine and install Truffle:

$ npm install truffle --global

Mental Models

Let's pause for a moment and grasp the core technical concepts.

The Protocol

Ethereum is a country and AZTEC is a forest.

In this country, people interact, do finance on dApps, move to different cities (wallets) and so forth. I like to think about AZTEC as a quiet woodland confined within the geography of the country. People can go there, declare their balance before stepping in, but after that transactions are confidential.

The stock picture below represents my (silly) attempt to portray the idea of fading into AZTEC. It's crystal clear what's going on in the normal environment (Ethereum), but the state of the world after one crosses the arch is fuzzy and concealed by the forest (AZTEC).

Notes

An AZTEC note is a first-class citizen and core primitive of the protocol. When you transact in zero-knowledge, smart contracts do NOT store any balances, but instead work with elliptic curve points, which are just computational noise to anyone who doesn't have the private keys.

It is very important to make a distinction between ERC20 and ERC1724, AZTEC's confidential token standard. The former stores a mapping between Ethereum addresses and unencrypted balances. The latter does encrypt the balances. I like to compare AZTEC notes with Bitcoin UTXOs, as the process of spending notes on AZTEC is very much similar.

The contents of a note, classified by their visibility:

Public
- Owner
- Encrypted Value
Private
- Spending Key
- Value

We're optimising for speed, so we stop with the fancy cryptography here. If you're hungry for more, check out our white paper.

Before continuing though, do note that AZTEC needs a trusted setup. This tutorial uses a trusted setup that was generated by our team internally. We will be releasing more information about the production trusted setup generation in the near future. Use at own risk.

Let's Do It

Clone this repo and install the node modules:

$ git clone git@github.com:PaulRBerg/confidential-tokens.git
$ cd confidential-tokens
$ npm install

If you get a lot of verbose logs related to "scrypt" and "keccak", that's perfectly fine because we require aztec.js which requires web3.js which subsequently has many cryptographic dependencies.

Before actually running the demo, there's a few important steps to do:

Create an accounts.js file inside the src folder. Only set two accounts. There is an example file called accounts.js.example.
Create a .env file at the root of the project and fill it with the properties below. Again, there is an example file called .env.example.
Deploy the confidential token contract to Rinkeby. You can use Truffle to do this:

$ truffle migrate --network rinkeby

Environment variables:

CONFIDENTIAL_TOKEN_ADDRESS: note that the actual contract name is ZKERC20, get this after truffle deploys the contract
MNEMONIC
INFURA_API_KEY

Now, check that your project looks like this:

Run the demo:

$ npm run demo

This is going to take a while, because transactions are sent to Rinkeby. After a few minutes, you should have a list of receipts printed in the console. Hooray, you just performed your first confidential token transfer on Ethereum!

Now, let's go through the source code in src/demo.js.

Create Notes

  aztecAccounts = [...new Array(2)].map(() => aztec.secp256k1.generateAccount());
  notes = [
    aztec.note.create(aztecAccounts[0].publicKey, 5),
    aztec.note.create(aztecAccounts[0].publicKey, 5),
    aztec.note.create(aztecAccounts[1].publicKey, 8),
    aztec.note.create(aztecAccounts[0].publicKey, 2)
  ];

Steps:

Generate a bunch of random accounts. We have to use "secp256k1" because AZTEC needs the accounts' public keys, not just their addresses.
Create 4 notes, with the first two belonging to the first account and the last two giving 8 tokens from the initial total amount (10) to the second account.

To better understand step 2, recall that AZTEC notes are similar in nature with Bitcoin UTXOs. When one transfers money, the leftover sums have to be converted into a new set of notes - this is by contrast to Ethereum canonical transactions, which use a balance model.

Also, I separated the accounts used in Ethereum (the ones in src/accounts.js) from the randomly generated AZTEC accounts (the demo script generates a file called aztecAccounts.json).

Create Dem Proofs

  proofs[0] = aztec.proof.joinSplit.encodeJoinSplitTransaction({
    inputNotes: [],
    outputNotes: notes.slice(0, 2),
    senderAddress: accounts[0].address,
    inputNoteOwners: [],
    publicOwner: accounts[0].address,
    kPublic: -10,
    aztecAddress: joinSplit.options.address,
  });

The proof object above:

Attests that publicOwner is happy to transfer 10 public ERC20 tokens into AZTEC form
Makes the first randomly generated AZTEC account the new owner (recall that the first two notes are worth 5 tokens each and are both owned by that AZTEC account)

  proofs[1] = aztec.proof.joinSplit.encodeJoinSplitTransaction({
    inputNotes: notes.slice(0, 2),
    outputNotes: notes.slice(2, 4),
    senderAddress: accounts[0].address,
    inputNoteOwners: [aztecAccounts[0], aztecAccounts[0]],
    publicOwner: accounts[0].address,
    kPublic: 0,
    aztecAddress: joinSplit.options.address,
  });

The second proof:

Transfers 8 tokens to the second AZTEC account in fully-fledged zero-knowledge form
Burns the first two input notes so that the first AZTEC account cannot reuse them in the future

  proofOutputs = proofs.map(({ expectedOutput }) => {
    return aztec.abiEncoder.outputCoder.getProofOutput(expectedOutput, 0);
  });
  proofHashes = proofOutputs.map(proofOutput => {
    return aztec.abiEncoder.outputCoder.hashProofOutput(proofOutput);
  });

We need the above to interact with a contract named "NoteRegistry", which is unique to every confidential token contract. You can think of proofHashes as an array of unique identifiers for the previously generated proofs.

Approve

  for (let i = 0; i < accounts.length; ++i) {
    const data = erc20Mintable
      .methods
      .approve(noteRegistry.options.address, scalingFactor.mul(tokensTransferred).toString(10))
      .encodeABI();
    await sendTx({
      from: accounts[i].address,
      to: aztecAddresses.erc20Mintable,
      data: data,
      privateKey: accounts[i].privateKey,
    });
  }

We mint a bunch of tokens and grant the NoteRegistry permission to spend from the ERC20 contract.

  const delta = 10;
  let data = noteRegistry
    .methods
    .publicApprove(proofHashes[0], delta)
    .encodeABI();
  await sendTx({
    from: accounts[0].address,
    to: noteRegistry.options.address,
    data: data,
    privateKey: accounts[0].privateKey,
  });

Just like ERC20, NoteRegistry needs to be granted permission to work with AZTEC proofs. We confess that this is an area of active research and we're investigating ways of making the development UX smoother.

Transfer

  let data = confidentialToken
    .methods
    .confidentialTransfer(proofs[0].proofData)
    .encodeABI();
  await sendTx({
    from: accounts[0].address,
    to: confidentialToken.options.address,
    data: data,
    privateKey: accounts[0].privateKey,
  });

  data = confidentialToken
    .methods
    .confidentialTransfer(proofs[1].proofData)
    .encodeABI();
  await sendTx({
    from: accounts[0].address,
    to: confidentialToken.options.address,
    data: data,
    privateKey: accounts[0].privateKey,
  });

Finally, the fun part: call the confidential token contract to make the transfers. Note that the first transaction only converts the ERC20 tokens, so third parties can find out how many tokens were transferred. However, the second transaction is fully confidential.

Here's a mindmap for what we just did:

Caveats

This tutorial uses a trusted setup that was generated by our team internally. We will be releasing more information about the production trusted setup generation in the near future. Use at own risk.
There's a ton of pre-approvals required before the confidential transfers can be triggered. As previously mentioned, this is something we're looking forward to improving.
The AZTEC codebase may go through multiple breaking changes after this article is published. Fear not though, this tutorial uses exact versions of npm packages to prevent disruption.
AZTEC uses Solidity 0.4.24, so you must use a compatible version of OpenZeppelin, that is 2.0.0
When the AZTEC contracts have only one user, confidentiality is leaked. Third parties can infer how much money is deposited due to ERC20's public nature - they can compare that against the total amount held by the contract. The more users join, the more confidentiality there is.

Packages

Here's an exhaustive list of AZTEC goodies we used:

The source code for all of them is available in our monorepo. Feel free to reach out on Twitter or email at hello@aztecprotocol.com if you have any questions!

Wrap-Up

I hope you enjoyed this tutorial and you're as excited about confidential transactions as I am. Check out these transactions which use a couple of AZTEC proofs to convert 10 ERC20 tokens into fully-fledged zero-knowledge form:

Many thanks to Zac Williamson, Arnaud Schenk and Tom Waite for their input and feedback.

Find me on Twitter or Keybase if you want to chat.

How to Write Upgradeable Smart Contracts with Truffle ^5.0 and ZeppelinOS ^2.0

Paul Berg — Sun, 30 Dec 2018 16:41:34 +0000

Context

In this post, we'll learn how to write upgradeable smart contracts with the latest versions of Truffle and ZeppelinOS. In particular, version ^5.0 of Truffle introduces a plethora of updates, with the most prominent one being the integration with web3 ^1.0. Let's unpack these updates and introduce upgradeable smart contracts with the state-of-the-art ZeppelinOS.

This is not an introductory article to Ethereum development, if you want that, take a look at the following resources:

Do note that the blockchain world moves at a ridiculous pace, giving little to no time for standards to sink in. This means that a lot of code snippets from the articles above may not work as expected, but don't panic and return here when that happens.

Prerequisites

Make sure you are equipped with the following:

node.js and npm
ganache-cli or the Ganache desktop app
curiosity to learn more

Truffle ^5.0

To install truffle globally, go to your terminal and write:

$ npm install truffle@^5.0.0 --global

And let's create our project:

$ mkdir MyProject
$ cd myProject
$ npm init -y
$ truffle init

This will initialise a bunch of files. If you used older versions of Truffle, you may notice that "truffle-config.js" is more verbose now and has many more configurable options. Let's go through the important changes.

Web3 ^1.0

This is a major API change, but it's a good one, because the new library is much more elegant and intuitive to use. Of course, there are transition costs if you had already written your Truffle tests using older versions, so bookmark the web3 ^1.0 documentation just in case.

HD Wallet Provider

If you were previously using the "truffle-hdwallet-provider" npm module, you must upgrade to "truffle-hdwallet-provider@web3-one" to make it work with Truffle ^5.0:

$ npm install truffle-hdwallet-provider@web3-one --save-dev

To load your mnemonic, you can either use the "fs" module natively provided by node or you can install "dotenv". Never hardcode it in JavaScript!

Bring Your Own Compiler

It used to be a huge pain in the neck to change the Solidity compiler when compiling with Truffle, but fear not any more! You can define whatever (remote) version you want by doing this:

compilers: {
  solc: {
    optimizer: {
      enabled: true,
      runs: 200,
    },
    version: "0.4.25",
  },
}

In this particular example, we set the compiler version to "0.4.25", but you can choose "0.4.24" or "0.4.18" if you want to. To list all the available versions:

$ truffle compile --list

Support for Async, Await

If you're a fan of JavaScript ES8's super duper cool "async" and "await", you can now make good use of them when running $ truffle develop or $ truffle console.

Others

There a few other new features, such as the added support for plugins, but they are outside the scope of this tutorial. Check out the changelog if you're looking for an exhaustive list.

Deploy a Smart Contract

This is the mock-up Solidity contract we're going to use:

// Note.sol
pragma solidity ^0.4.25;

contract Note  {
  uint256 private number;

  constructor(uint256 _number) public {
    number = _number;
  }

  function getNumber() public view returns (uint256 _number) {
    return number;
  }
}

Create a new file called "Note.sol" in your "contracts" folder and copy and paste the code above in there. Now, make sure you've done all the steps correctly by compiling the contract:

$ truffle compile

You should get no error and the following logs:

Compiling ./contracts/Migrations.sol...

Compiling ./contracts/Note.sol...

Writing artifacts to ./build/contracts

Now, let's write the migration file.

// 2_migrate_note.js

var Note = artifacts.require("./Note.sol");

module.exports = function (deployer) {
  deployer.deploy(Note, 64);
};

In the "migrations" folder, create a new file called "2_migrate_note.js" and copy and paste the code above. To verify the set up, you have to first spin up an Ethereum node, but don't worry, for local development there are tools like Ganache. You can run it either by opening a new terminal window and executing $ ganache-cli or by launching the desktop app. Then:

$ truffle migrate

If you encounter problems, make sure that your "truffle-config.js" file looks like this (I stripped the comments for brevity):

// truffle-config.js

module.exports = {
  compilers: {
    solc: {
      version: "0.4.25",
      settings: {
        optimizer: {
          enabled: false,
          runs: 200
        }
      }
    }
  },
  networks: {
    development: {
      host: "127.0.0.1",
      port: 8545,
      network_id: "*",
    }
  }
};

If it works, you should get a beautiful report like the one here. Awesome! Now you know how to compile and deploy a contract with Truffle ^5.0, but you haven't got your hands dirty with the cooler part yet: making the smart contracts upgradeable.

ZeppelinOS

Set Up

If you're completely unfamiliar with upgradeable smart contracts, go watch Elena Nadolinski's presentation on the topic. It's totally worth it and it can do a much better job than someone can on a blog.

The gist of it is that we're aiming to reconcile traditional development practices with smart contracts:

When running A/B testing with real users and there's a bug, we should patch the code and fix it asap.
The upgradeability processes should remain fully transparent and not grant total power to the developer(s).

Point no. 2 is currently under research with many people actively proposing transparent governance models. However, we won't mind decentralised autonomous organisations (DAOs) for now and focus on the technical part of the story.

Let's install ZeppelinOS and its library dependency:

npm install zos --global
npm install zos-lib --save-dev

And then initialise it within our Truffle project:

zos init MyProject

A file called "zos.json" should've been initialised:

{
  "zosversion": "2",
  "name": "MyProject",
  "version": "0.1.0",
  "contracts": {}
}

Importantly, make sure to update the Note contract as follows:

// Note.sol
pragma solidity ^0.4.25;

import "zos-lib/contracts/Initializable.sol";

contract Note is Initializable {
  uint256 private number;

  function initialize(uint256 _number) public initializer {
    number = _number;
  }

  function getNumber() public view returns (uint256 _number) {
    return number;
  }
}

ZeppelinOS contracts don't use normal Solidity constructors but instead rely on an "Initializable" base contract which needs to have its "initialize" function overridden. Let's continue by adding the edited contract to ZeppelinOS:

$ zos add Note

The following JavaScript object should've been added to "zos.json":

"contracts": {
  "Note": "Note"
}

Before deployment, ZeppelinOS requires you to create a session:

$ zos session --network development --from YOUR_DEPLOYMENT_ACCOUNT --expires 7200

Explaining each parameter:

network: one of the networks defined under "truffle-config.js"
from: because of a known transparent proxy issue, the deployment account mustn't be the default address designated by truffle or ganache
expires: the time-to-live of the session, measured in seconds

Now, to clarify a few things:

The session is sort of a "behavioural sugar" - while deploying, you don't have to specify the "network" and the "from" parameters.
You might wonder what "from" parameter to set. Simply put, any account except the first one. Find a picture below for an example on the Ganache desktop app:

Ready for prime time?

$ zos push

If it worked, you should've got something like this:

Compiling contracts

Compiling ./contracts/Migrations.sol...

Compiling ./contracts/Note.sol...

Compiling zos-lib/contracts/Initializable.sol...

Writing artifacts to ./build/contracts

Validating contract Note

Uploading Note contract as Note

Deploying logic contract for Note

Created zos.dev-7923.json

This command finally deploys your smart contract to the blockchain and it also creates a file called "zos.dev-<network_id>.json", where "<network_id>" is the id of your Ethereum network. This is where you can find important information about your project, such as the addresses of your deployed contracts.

Upgradeability

It is highly important to understand that ZeppelinOS, under the hood, works by creating two contracts:

Proxy
Logic

The catch is that the Proxy redirects the end user to the Logic, but the Proxy "retains" the storage. That is, even if you update the Logic, the state of your smart contracts stays the same.

Previously, you created and deployed a Logic contract. Let's create an instance of a Proxy:

$ zos create Note --init initialize --args 64

This deploys and logs the address of the new Proxy contract. Open a new terminal window and initialise a Truffle console:

truffle console --network development
let abi = require("./build/contracts/Note.json").abi
let contract = new web3.eth.Contract(abi, "your-proxy-address")
contract.methods.getNumber().call();

It should print "64".

Head to the web3 ^1.0 docs for more information on how to work with the new Contract API.

What if you want to change the number? Fortunately, you can make an upgrade to the logic of the contract, while preserving the storage.

Firstly, update the contract by adding a new function:

// Note.sol
pragma solidity ^0.4.25;

import "zos-lib/contracts/Initializable.sol";

contract Note is Initializable {
  uint256 private number;

  function initialize(uint256 _number) public initializer {
    number = _number;
  }

  function getNumber() public view returns (uint256 _number) {
    return number;
  }

  function setNumber(uint256 _number) public {
    number = _number;
  }
}

And then:

$ zos push
$ zos update Note

Logs should look like this:

Using session with network development, sender address 0xd833B5fa468A5a430a890390D8Ec652142836019

Upgrading proxy to logic contract 0xe6d6d1cd339f129275e5b5e7ab39d85bc5642010

Instance at 0x746bb4a872bdfd861c4af5dd9391b3fb5b22fb7a upgraded

0x746bb4a872bdfd861c4af5dd9391b3fb5b22fb7a

Updated zos.dev-7923.json

Now, start a new Truffle console and call your new "setNumber" function:

$ truffle console --network development
let abi = require("./build/contracts/Note.json").abi;
let contract = new web3.eth.Contract(abi, "your-proxy-address");
contract.methods.getNumber().call();
contract.methods.setNumber(65).send({ from: YOUR_OTHER_ACCOUNT });
contract.methods.getNumber().call();

It should print "65".

Voilà! You just wrote, deployed and upgraded an Ethereum smart contract.

Caveats

"YOUR_DEPLOYMENT_ACCOUNT" must only be used when setting up a session, for any other interaction with the contract, you have to use other account.
If you got a A network name must be provided to execute the requested action error, just start a new session, the old one expired.
You might've noticed that we didn't use TruffleContract to interact with the deployed contracts and instead relied on the web3 ^1.0 implementation. This is because I find the former confusing and, on many occasions[1][2], not even functional.
There is more to upgradeable smart contracts than what we discussed here. Head to Zeppelin's awesome documentation to get the whole picture. In particular, I recommend looking over the limitations to upgrading storage variables.
If you're planning to migrate to Solidity ^0.5.0, I'm sorry to disappoint you that ZeppelinOS doesn't support it yet, as of Dec 2018. There is an option called "--skip-compile", but I felt that it added too much complexity to be worth it. Santiago Palladino from Zeppelin reached out on Twitter and announced that they now do support the ^0.5.0 versions of Solidity. If you want to test it out, just do npm install zos-lib@2.1.0-rc.0 --global.

Wrap-Up

I hope you enjoyed this tutorial and you're as excited about blockchain development as I am, despite the occasional versioning and coordination issues.

I compiled the code used throughout this article in this GitHub repo. There are three branches (master, zos, zos-upgraded) with the correspondent code of the Note contract for every stage we've been through.

Find me on Twitter or Keybase if you want to chat.

How to Host a Static Website with S3, CloudFront and Route53

Paul Berg — Thu, 27 Dec 2018 22:45:34 +0000

Context

I recently set-up my self-hosted personal blog and I underestimated the effort I had to put in to make it exactly as I wanted to:

Pay-as-you-go hosting
SSL certificate
Functional www subdomain
Highly customisable but minimalistic design
Markdown-powered articles

I decided to write a tutorial to help others do it with less overhead. This article will go into fine details on how to tick all the boxes above, with a focus on the back-end components. For 4 and 5, I used Hugo with the Minimal theme.

Caveat

Do note that this is a verbose tutorial, aimed at those who value flexibility and interoperability with other AWS services more than anything else. If you're just looking for something light and quick, you may want to use Netlify or Amplify.

Prerequisites

I will further assume that:

You designed and coded your website or at least have a mock-up.
You have an AWS account (if not, go register one, first year has a free tier).
You are familiar with DNS and how it works, at least at a high level.

Regarding DNS, a quick explanation is that it's sort of the directory of the Internet and, just like Google owns "google.com", you can own "example.com" as well. To do it, you have to go a DNS registrar and purchase your the domain you want. I strongly recommend using Namecheap as your registrar, as they have an awesome UI and low prices. As an alternative, you could choose GoDaddy.

In case your ".com" domain is taken and you want some clever mashups:

After you purchase it, don't set any DNS records yet. We'll do that later once we get to Route53.

Hosting with Amazon

As mentioned above, the goal is to use a pay-as-you-go service because it's by far the most cost-effective option out there. I used to pay a fixed cost in the range of tens of USD per month for a server even if I had periods when there was hardly any activity on it. Go modular, go with AWS!

Before jumping in, it's important to grasp the nomenclature:

AWS: Amazon Web Services
S3: Simple Storage Service, for storing files
Route53: a service for handling DNS records
CloudFront: content delivery network (CDN) for speeding up your website, also required to generate the SSL certificate

Here's a neat mindmap designed with Cloudcraft for what you're going to build:

We'll first focus on the path on the right-hand side, so the normal configuration, not the one for the www subdomain. Importantly, using this modular configuration, you won't run any back-end Linux server at all, so you don't have mind updating or patching anything. How convenient is that?

S3

This is where you'll store your static files (HTML, CSS, JS). If you used Create React App or some other frontend development framework, look after your generated "build" or "public" folder.

Here's what you have to do:

Set up an S3 bucket named "example.com". Notice that S3 bucket names are global and, just like with domains, you have to find an alternative if someone reserved "example.com" before you. Based on your needs, you can enable or disable the options AWS provides you: versioning, server access logging, encryption etc.
Make sure to uncheck the boxes that mention blocking and removing public access ACLs and policies. Many times, S3 buckets are used to store private data, so AWS optimises for highly secure configurations. In your case though, you want to have the bucket publicly accessible.
Make sure to set a policy, here's an example.
Activate "Static website hosting" for your bucket and check "Use this bucket to host a website"
Upload your files, making sure "index.html" is at the root of your bucket

All the operations above can be done using either the AWS administrator interface or the CLI. Specifically for step 4 though, I'd recommend doing it in the console so that you can get the endpoint for your new hosted website (I hid mine for privacy reasons):

Test it out in the browser to make sure you set up your S3 bucket correctly. It should like this:

example.com.s3-website.your-region.amazonaws.com

CloudFront

To host a static website, you don't actually need CloudFront or any other CDN, because there's not much data to store and the gains in efficiency and UX are little. However, one of the original goals was to have a website secured by an SSL certificate.

Now, you might've heard about CloudFlare, which is arguably the easiest way to get up and running with a CDN and also benefit of some SSL security. I say "some" because they have this misleading featurea called "Flexible SSL", which doesn't have the security guarantees a self-signed SSL certificate has.

Therefore, you're not going to use that, but instead make use of a similar service in AWS called CloudFront. You can think of it as having your own content distribution servers, as data is cached in multiple locations on Earth to provide your users fast response times. More important for the static website, it also makes possible using an SSL certificate.

Again, you can create your CloudFront distribution using the AWS administrator interface or the CLI tool. Here's an example configuration.

Caveats:

The origin name should be the endpoint you got after activating "Static website hosting" on your S3 bucket.
Do NOT set any "DefaultRootObject". Leave it empty.
Allow both HTTP and HTTPS. You'll be able to automatically redirect users from HTTP to HTTPS after the certificate is signed and installed.

Make sure to wait a while for the distribution to properly boot (can take up to 15 minutes). Test it by opening the endpoint you receive, your S3 static website should pop. The endpoint should look like this:

13fb4knzujxq0b.cloudfront.net

Note it somewhere because we'll use it with Route53 in a sec.

Route53

It's time to connect the domain you bought on your DNS registrar with CloudFront and S3. Route53 acts as the bridge for that.

Create a Route53 hosted zone and set your domain. Make it public.
You'll be given 4 NS records. Copy and paste the nameservers in your external domain administration page. If you're using Namecheap, here's how you can update your nameservers. Go to Account -> Dashboard -> Manage -> Nameservers -> Custom DNS and put your 4 nameservers in there:
Create a record set and leave the name empty (it will default to example.com). Then:
- Set the type to "A - IPv4 address"
- Respond with "Yes" to "Alias" and set the alias target to your CloudFront distribution url.
- Keep the routing policy as "Simple" and, based on your budget and needs, enable or disable "Evaluate Target Health".
Repeat step 3 for type "AAAA - IPv6 address" if you enabled your CloudFront distribution to be IPv6 compatible; if you followed this tutorial, IPv6 was enabled by default.

Note that DNS propagation can take up to 72 hours, although it should be normally updated within a few hours or faster. If you previously set any other DNS records (like MX for work emails), you'll have to reset them in Route53.

WWWhat now?

Congrats for getting this far! I'm sorry to let you know that now you have to repeat all the previous three steps. Yes, you heard that right, because of the elusive way the Internet works, "www" is not something included as a holistic component of HTTP.

It is important to point out that it's really not mandatory to add a www subdomain to your website and you can safely proceed to the next step if you're fine with your end users not being able to access your website via "www.example.com". I was a bit pedantic about it and I simply had to add the www subdomain.

Notes:

Redo only S3, CloudFront and Route53, you don't have to (and can't) go to Namecheap to buy "www.example.com".
For all the fields where you were asked to put "example.com", now put "www.example.com".

If you wonder whether by creating S3 buckets means you are required to deploy your static files to both of them, the answer is no, you don't have to do that. When you activate "Static website hosting" for your second S3 bucket, select "Redirect requests" instead of "Use this bucket to host a website":

SSL certificate

Let's Encrypt (LE) is one of the best things that happened to the Internet in the last couple of years. They have democratised access to SSL certificates and this is a huge accomplishment, kudos to them! If LE was so helpful to you, consider making a donation.

This step is crucial and also the hardest in the whole tutorial, so proceed carefully. You could use either your own machine or a Linux server to generate the certificate, but I chose the former option, it's simpler and less expensive.

Head to the certbot-s3front repo and install the tool. You need to have Python and pip installed.
Follow their instructions, but:
- Skip the S3 and CloudFront parts, you had already done that.
- Set "example.com,www.example.com" as the value for the "-d" (domain) parameter. Read more about this on the LE forum.
After you successfully generate your SSL certificate, you could optionally enable "Redirect HTTP to HTTPS" on your naked domain (that is, "example.com") CloudFront distribution. Don't do this for "www", as it'll redirect to your naked domain anyway.
Make sure to backup your /etc/letsencrypt/live/example.com certificate(s).

Notes:

Due to mysterious reasons, I couldn't make certbot's authentication work by setting the "AWS_ACCESS_KEY_ID" and "AWS_SECRET_ACCESS_KEY" environment variables. This might be caused by the fact that I have several different profiles in my ~/.aws/credentials, but I'm not sure. To avoid a "NoCredentialsError", just temporarily set a "default" profile and certbot will pick that up.
If you're unlucky like me and you get a further "IAMCertificateId" error, check out this solution.

ACM

Optionally, you could use the AWS Certificate Manager (ACM). Shortly after this article was published, a lot of people jumped in to say that it'd be much easier to use ACM for generating certificates. No need to think about renewals, but it means you're locked in with AWS.

Bottlenecks

No server logic: This tutorial is only applicable to static websites, so you cannot run any back-end logic using a node.js module like express. For that, you can either spin up an EC2 instance, write Lambda functions or use Docker via ECS/ Kubernetes.
LE certificates expire in 90 days: You can solve this in two ways. Firstly, you could set a reminder in your calendar, which I admit it's suboptimal, but I'm in an experimentation phase so I'm not bothered by a bit of manual work. Secondly, you could set a cron job, but you need a Linux server and use the "--renew-by-default --text" options when interacting with certbot.
Rich link previews can be a mess: This could be a problem specific to my Hugo theme, but I also think everyone wants to have a proper preview image and description when sharing their website links. Here's how I managed to do it.

Wrap-Up

Congrats, you now have a really cheap but still highly flexible static website! Billing stats for 100-1000 monthly active visitors and fairly frequent S3 deployments are between $1 and $2, so this is a steal! For usage way beyond that, you may need to upgrade your AWS components, but this is outside the scope of this tutorial.

If you're an experienced developer interested to replicate this tutorial on multiple AWS accounts, you may want to check out Terraform. It's a super duper cool Infrastructure-as-a-Service tool which you can use to define your S3, CloudFront and Route53 as code snippets. Isn't technology so dang amazing?

Hope you find this tutorial helpful! Find me on Twitter or Keybase if you want to chat.

Credits

Amazon for the AWS, S3, CloudFront and Route53 logos