pt-br docs

.gitignore

@@ -3,3 +3,4 @@
 node_modules/
 tools/runkeeper/
 docker-compose.override.yml
+package-lock.json

README.pt-br.md

@@ -0,0 +1,10 @@
+# Blockchain Demo
+
+Uma demonstração web sobre conceitos de blockchain.
+
+Leia em:
+
+1. https://blockchain4devs.github.io/blockchain-demo/docs/pt-br/
+2. [https://blockchain4devs.github.io/blockchain-demo/docs/pt-br/blockchain-demo.pdf (PDF)](https://blockchain4devs.github.io/blockchain-demo/docs/pt-br/blockchain-demo.pdf)
+
+Os fontes desses docucumentos estão disponíveis no diretório [docs/pt-br](docs/pt-br).

docs/pt-br/.gitignore

@@ -0,0 +1,3 @@
+/index.*
+!/index.adoc
+/blockchain-demo.*

docs/pt-br/build

@@ -0,0 +1,96 @@
+#!/bin/bash
+set +x
+set -e
+
+BASE_DIR=`cd "$(dirname "$0")"; pwd`
+PROJECT_DIR=`cd "$BASE_DIR/../.."; pwd`
+RELATIVE_DIR=${BASE_DIR##$PROJECT_DIR/}
+
+config=build.conf
+[ -f "$BASE_DIR"/$config ] || config=$config.sample
+source "$BASE_DIR"/$config
+
+# called automatically when you invoke this script
+check_prerequisites() {
+  which asciidoctor > /dev/null || {
+    echo "ERROR: install asciidoctor first!"
+    exit 1
+  }
+
+  if $generate_pdf
+  then
+    if $use_fopub
+    then
+      [ -x "$fopub" ] || {
+        echo "ERROR: can't execute $fopub!"
+        exit 1
+      }
+    else
+      which asciidoctor-pdf > /dev/null || {
+        echo "ERROR: install asciidoctor-pdf first!"
+        exit 1
+      }
+    fi
+  fi
+}
+
+# used to remove generated docs (HTML and/or PDF)
+_clean() {
+  rm -f index.{html,xml}
+  rm -f $pdf_name $xml_name
+}
+
+# used to build the main doc (HTML and/or PDF)
+_build() {
+  local result
+
+  asciidoctor index.adoc
+  result=$?
+
+  $generate_pdf || exit $result
+
+  if $use_fopub
+  then
+    asciidoctor -b docbook -d book -a data-uri! index.adoc -o $xml_name
+    $fopub $xml_name
+  else
+    asciidoctor-pdf -o $pdf_name index.adoc
+  fi
+}
+
+# used to publish the generated docs to GitHub Pages
+_publish() {
+  local published_dir=`mktemp -d`
+  local remote_repo=`git config --get remote.origin.url`
+  [ ".$remote_repo" = "." ] && {
+    echo 'The remote repository is not configured!'
+    return 1
+  }
+
+  mkdir -p "$published_dir/$RELATIVE_DIR"
+  rsync -av --delete \
+    --include='*.html' \
+    --include='*.pdf' \
+    --include='images/' \
+    --include='images/**' \
+    --exclude='*' \
+    . $published_dir/$RELATIVE_DIR/
+
+  local msg="Published at `date`"
+  cd "$published_dir"
+  git init
+  git add -A
+  git commit -m "$msg"
+  git push --force $remote_repo master:gh-pages
+  cd - &> /dev/null
+}
+
+check_prerequisites
+cd "$BASE_DIR"
+op=$1
+[ "$op" ] || op=build
+type _$op &> /dev/null || {
+  echo "Usage: `basename $0` [build]|<clean|publish>"
+  exit 1
+}
+_$op

docs/pt-br/build.conf.sample

@@ -0,0 +1,7 @@
+#!/bin/bash
+
+generate_pdf=${generate_pdf:-true}
+use_fopub=${use_fopub:-false}
+pdf_name=${pdf_name:-blockchain-demo.pdf}
+xml_name=${pdf_name%.pdf}.xml
+fopub=${fopub:-~/Projects/github.com/asciidoctor/asciidoctor-fopub/bin/fopub}

docs/pt-br/definitions.adoc

@@ -0,0 +1,12 @@
+:PauloJeronimo: {uri-paulojeronimo}[Paulo Jerônimo]
+:AndersBrownworth: {uri-andersbrownworth}[Anders Brownworth]
+:blockchain4devs: {uri-blockchain4devs}[blockchain4devs]
+:blockchain-demo-src: {uri-blockchain4devs}/blockchain-demo
+:blockchain: Blockchain
+:rootdir: link:{uri-blockchain-demo-2}[blockchain-demo]
+:macOS: {uri-macOS}[macOS]
+
+ifdef::backend-html5[]
+:rootdir: ../..
+:blockchain: pass:[<b>Blockchain</b>]
+endif::[]

docs/pt-br/demonstracao/a-blockchain-utilizada-no-controle-de-transacoes/coinbase-transactions.adoc

@@ -0,0 +1,46 @@
+[[coinbase-transactions]]
+= Transações Gênese
+
+Como vimos uma {blockchain} voltada ao controle de transações precisa manter um registro imutável dessas transações.
+Mas, além disso, em se tratando de transações, é essencial conseguirmos verificar se elas realmente são válidas.
+Num sistema financeiro, para que uma pessoa possa gastar algum dinheiro, ela precisa ter saldo, óbvio.
+Então, esse dinheiro deve ter vindo de alguém que, por sua vez, recebeu de outro alguém e assim suscessivamente.
+Voltando no tempo dessa forma, chegaremos até o ponto em que o dinheiro surgiu.
+
+Poderíamos nos imaginar na figura de mineradores reais.
+Encontrando uma mina de ouro, utilizaríamos parte do ouro que minerássesmos para trocá-lo por coisas.
+Devemos nos lembrar que toda mina de ouro é finita.
+A moeda (o ouro nesse caso) é simplesmente algo que utilizamos para facilitar uma troca por algo que queremos.
+As pessoas que recebem esse ouro, por sua vez, poderiam dividí-lo em porções ainda menores para comprar coisas de outras pessoas.
+O Bitcoin funciona exatamente assim, como o ouro.
+
+Vamos fazer uma representação sistêmica desse processo.
+Para entender como surge o dinheiro numa {blockchain}, precisamos definir o {uri-coinbase-transaction}[conceito de transação gênese] (ou transação coinbase).
+
+Nessa demonstração, {AndersBrownworth} é o "descobridor de uma mina".
+Sendo assim, a primeira coisa que ele faz é criar para si um {uri-genesis-block}[bloco gênese], de identificador 1.
+Esse bloco não contém nenhuma transação além de uma, especial, chamada de `Coinbase`.
+Essa transação especial é de "ninguém" para a pessoa que criou o bloco, no caso, um minerador.
+Nessa {blockchain}, Anders resolve se dar 100 dólares no primeiro bloco (1).
+
+[NOTE]
+====
+* O {uri-blockchain-genesis-block}[bloco gênese na Blockchain do Bitcoin], criada por {uri-satoshi-nakamoto}[Satoshi Nakamoto] tem o identificador 0.
+* No caso do Bitcoin, o valor de {uri-coinbase}[Coinbase] foi de 50 BTC quando a rede foi criada.
+Em seguida, caiu para 25 e, no ano passado, foi para 12.5 BTC. Esse valor sempre decairá.
+* No Bitcoin, o valor de `Coinbase` é um valor que é reivindicado por um minerador como prêmio pela mineração do bloco.
+====
+
+No bloco 2, existem transações.
+O importante nessa implementação de {blockchain} é que, agora, dá pra saber se uma transação é válida.
+Vejamos como.
+
+No bloco 4, por exemplo, Sophia transfere para Jackson, 8 dólares.
+Será que Sophia realmente tinha 8 dólares?
+Para saber isso, vamos ao bloco anterior (3).
+Sophia não teve transações nesse bloco.
+Vamos ao anterior novamente (2).
+Nesse bloco, Sophia recebeu, de Anders, 10 dólares.
+Então, sem dúvida, Sophia pode gastar esse dinheiro.
+
+Portanto, com essa nova implementação de {blockchain}, agora conseguimos verificar se uma transação é válida.

docs/pt-br/demonstracao/a-blockchain-utilizada-no-controle-de-transacoes/index.adoc

@@ -0,0 +1,10 @@
+[[a-blockchain-utilizada-no-controle-de-transacoes]]
+= A Blockchain utilizada no controle de transações icon:dollar[]
+
+:leveloffset: +1
+
+include::tokens.adoc[]
+
+include::coinbase-transactions.adoc[]
+
+:leveloffset: -1

docs/pt-br/demonstracao/a-blockchain-utilizada-no-controle-de-transacoes/tokens.adoc

@@ -0,0 +1,41 @@
+[[tokens]]
+= Tokens
+
+Na {uri-blockchain-demo-tokens}[aba Tokens] visualizamos uma das possíveis aplicações da {blockchain}.
+Ela pode ser utilizada para um sistema financeiro.
+Em essência, <<a-origem-da-blockchain,como já citado>>, a origem da {blockchain} foi para tornar possível a existência do {uri-bitcoin-paper}[Bitcoin].
+Em inglês, o termo https://www.google.com.br/search?q=what+is+a+token[token] é dado para uma coisa que esteja servindo como uma representação visível ou tangível de um fato, qualidade, sentimento, etc.
+Dessa forma o campo `Data` numa {blockchain} pode representar um `token` que, nesse contexto, significa um registro de várias transações.
+Cada transação, por sua vez, registra que pessoa está enviando uma quantia (em moeda icon:dollar[]) para outra pessoa.
+
+Como já vimos, o registro de dados numa {blockchain} é imutável.
+Logo, se esses dados forem transações, elas também serão imutáveis.
+E, num registro dessa espécie, é essencial essa imutabilidade pois nenhuma pessoa de boa fé gostaria de ver transações sendo adulteradas.
+A {blockchain} resolve isso.
+Se tentarmos fazer uma alteração nos dados de qualquer transação poderemos notar que o bloco será invalidado.
+
+Nessa demonstração, as transações são representadas de forma muito simplificada.
+Basicamente, cada transação possui apenas três (3) campos: quem está enviando um valor, quem está recebendo e, por fim, o valor.
+Fundamentalmente, para um sistema de transações, essas são as três informações chave.
+É muito importante que saibamos de onde uma quantia saiu e para onde ela foi.
+
+É claro que apenas essas três informações não são suficientes para se contruir um sistema realmente utilizável.
+Afinal, as pessoas querem privacidade e anonimato por razões óbvia (de segurança).
+Ninguém utilizaria um sistema, como esse, onde estão públicas as informações do nome da pessoa e dos valores que ela movimenta.
+Então, num sistema como o Bitcoin, ao invés de utilizarmos nomes, utilizamos endereços.
+
+Da mesma forma que não queremos adulterações nos dados, devemos evitar outras possibilidades de fraudes.
+Há um tipo de fraude que não seria possível de ser verificada numa {blockchain} implementada da forma como estamos fazendo agora.
+Essa fraude seria uma pessoa tentar "gastar" o mesmo diheiro duas vezes.
+Isso é conhecido como "gasto duplo".
+
+Exemplificando a possibilidade de gasto duplo através de um passo a passo:
+
+. Darcy tem 25 dólares e quer comprar algo de Bingley.
+. Ela passa seus 25 dólares para o Bingley.
+. Utilizando essa {blockchain}, ela também tenta comprar algo de Jane, gastando mais 25 dólares.
+. O problema: será que Darcy tinha, realmente, 50 dólares?
+Ou será que ela está tentando gastar os mesmos 25 dólares que já possuia?
+Como nessa {blockchain} não há o registro do saldo anterior de Darcy, isso poderia ser possível. Concorda?
+
+Então, claramente, essa {blockchain} precisa ser evoluída.

docs/pt-br/demonstracao/index.adoc

@@ -0,0 +1,16 @@
+[[demonstracao]]
+= Demonstração
+
+:srcdir: ../../..
+
+:leveloffset: +1
+
+include::o-que-e-um-hash.adoc[]
+
+include::o-que-e-um-bloco.adoc[]
+
+include::o-que-e-uma-blockchain/index.adoc[]
+
+include::a-blockchain-utilizada-no-controle-de-transacoes/index.adoc[]
+
+:leveloffset: -1

docs/pt-br/demonstracao/o-que-e-um-bloco.adoc

@@ -0,0 +1,34 @@
+[[o-que-e-um-bloco]]
+= O que é um Bloco?
+
+Vamos agora para a {uri-blockchain-demo-block}[aba Block].
+Adicionaremos, acima do campo `Data` aprensentado na aba `Hash`, dois outros campos: `Block` e `Nonce`.
+Eles serão explicados agora.
+Também vamos criar um botão `Miner` e explicar qual será sua utilidade.
+Com a adição desses novos elementos, estamos criando o que chamaremos de *Bloco*.
+
+Um bloco, então, tem um número identificador (`Block`), um `Nonce`, e pode ser "minerado" quado clicarmos no botão `Miner`.
+Também notemos que o campo `Hash` agora possui um valor interessante, iniciado por quatro zeros ("0000").
+Esse valor de `Hash` é bastante singular.
+Ele é criado através de uma *regra que é utilizada para verificar se o bloco é válido*.
+Nesse nosso caso, a regra é bem simples: o valor do `Hash`, calculado em função do valor inserido em `Data` (e dos outros campos), precisará começar com esses quatro zeros.
+
+Para encontar um `Hash` que safisfaça essa regra, após inserir os dados que desejamos no campo `Data`, iremos alterar o valor de `Nonce`.
+O número identificador do bloco (`Block`) será gerado automaticamente (apesar de podermos modificá-lo, para testes, nesse exemplo).
+Esse cáculo do `Hash` será repetidamente refeito, até encontarmos um `Hash` que comece com esses quatro zeros.
+
+Você pode notar também que, qualquer mudança nos campos (`Block`, `Nonce` e `Data`) altera o valor de `Hash`.
+
+Manualmente, poderíamos ficar tentando modificar o valor de `Nonce` até encontarmos a solução para esse problema.
+Mas, fazendo isso, poderemos passar vários minutos ou horas (ou mesmo dias) em tentativas.
+Então, o botão `Miner` servirá para realizar essa tarefa pra nós.
+
+A atividade de {uri-mining}["mineração"], então, é nesse nosso caso uma tarefa que será executada pelo computador.
+Ela será realizada em função do valor de todos os campos e buscará um `Hash` que atenda a regra estabelecida: começar com quatro zeros.
+Essa regra também é conhecida por "desafio matemático".
+Você pode notar que esse desafio (no nosso caso e em várias outras formas de propô-lo) não é uma função complexa.
+Por outro lado, ela é onerosa pois pode cosumir muito tempo de processamento.
+O trabalho de "mineração" realizado dessa forma é também conhecido por {uri-proof-of-work}["Proof of Work"].
+
+Após um bloco ser "minerado", a conferência de sua validade é algo extremamente simples e rápido.
+Essa conferência é apenas o cálculo do `Hash` de todos os campos (`Block` + `Nonce` + `Data`) e a obediência a regra estabelecida (em nosso caso, um `Hash` começando com quatro zeros iniciais).

docs/pt-br/demonstracao/o-que-e-um-hash.adoc

@@ -0,0 +1,67 @@
+[[o-que-e-um-hash]]
+= O que é um Hash?
+
+Hashes são parte de várias informações armazenadas na {blockchain} e são essenciais para garantir sua segurança.
+
+Matematicamente falando, uma {uri-funcao-hash}[função hash] é um algoritmo que mapeia dados de comprimento variável para dados de comprimento fixo.
+Os valores retornados por uma função hash são chamados valores hash, códigos hash, somas hash, checksums ou, simplesmente, hashes.
+
+Nessa demonstração, a {uri-blockchain-demo-hash}[aba Hash] possibilita a entrada de uma informação de tamanho qualquer (no campo `Data`) e produz um `Hash` de tamanho fixo.
+A função SHA256 é uma das variantes do {uri-sha-2}[SHA-2] e utilizada para gerar esse código hash.
+Esse código é geralmente representado por uma string de 64 caracteres hexadecimais (de "0" a "9" e de "a" a "f").
+Obviamente, além dessa função, existem várias outras que poderiam ser utilizadas para gerar uma string de tamanho fixo a partir de uma quantidade de dados variáveis.
+Outros exemplos de funções (dentre várias) são o MD5 e o SHA-1.
+
+Ao se gerar um hash, espera-se que a cadeia fixa produzida a partir de um conjunto de informações tenha sempre um valor diferente para outro conjunto de entrada.
+Se o hash gerado num conjunto de dados for igual ao de outro, ocorre o que chamamos de colisão.
+Quanto menos colisões houverem ao se gerar um hash para um conjunto de informações diferentes, melhor o algoritmo de Hash.
+
+Foram necessários 20 anos para que fosse {uri-announcing-first-sha1-collision}[anunciada a primeira colisão de hash para a função SHA-1].
+Isso quer dizer que esse algoritmo foi considerado seguro e utilizado por todo esse espaço de tempo, sem problemas.
+O site {uri-shattered} demonstra que, para se proferir um ataque onde se tentaria obter um hash igual para um `input` diferente utilizando o algoritmo SHA-1, seriam necessárias 9.223.372.036.854.775.808 de execuções do algoritmo.
+Ou seja, um número monstruoso de compressões.
+Para ser realizado esse número de compressões, seriam necessários 6.500 anos de processamento de uma CPU comum (ou 110 anos de uma GPU).
+
+Uma colisão de SHA-1 pode ser visualizada, como na execução/resultado dos comandos apresentados a seguir:
+
+[NOTE]
+====
+Essa execução/resultado de comandos é feita num shell (Bash) de um {macOS}.
+Mas, ela também pode ser adaptada e realizada em outros sistemas operacionais.
+====
+
+----
+$ for n in 1 2; do curl -s -O https://shattered.it/static/shattered-$n.pdf; done
+$ open shattered-*.pdf
+$ diff shattered-*.pdf
+Binary files shattered-1.pdf and shattered-2.pdf differ
+$ shasum shattered-*.pdf
+38762cf7f55934b34d179ae6a4c80cadccbb7f0a  shattered-1.pdf
+38762cf7f55934b34d179ae6a4c80cadccbb7f0a  shattered-2.pdf
+----
+
+O código JavaScript da {uri-blockchain-demo-hash}[aba Hash] (`views/hash.jade`) é um código escrito em {uri-jade}[Jade].
+Ele calcula o hash através de um código (em JavaScript) que executa a função sha256.
+
+[source,javascript]
+.public/javascripts/lib/sha256.js
+----
+include::{srcdir}/public/javascripts/blockchain.js[lines=1..4]
+----
+
+Obviamente, a função hash implementada em JavaScript também deve produzir o mesmo resultado que uma função que pode ser chamada via linha de comando.
+Sendo assim, também é possível gerar o hash de uma string informada no quadro `Data` através de uma linha de comando (em Bash, por exemplo).
+
+O Hash para a string vazia (valor inicial do quadro), pode ser calculado assim:
+
+----
+echo -n ''|shasum -a 256
+----
+
+Então, o hash de "Paulo Jerônimo" poderia ser calculado assim:
+
+----
+echo -n 'Paulo Jerônimo'|shasum -a 256
+----
+
+Para se aprofundar um pouco mais em funções hash aplicadas a moedas digitais e saber quando colisões em valores de hash tem importância nesse contexto, recomenda-se a leitura do artigo {uri-history-of-hash-function-attacks}["Lessons From The History Of Attacks On Secure Hash Functions"].

docs/pt-br/demonstracao/o-que-e-uma-blockchain/a-blockchain-e-distribuida-e-descentralizada.adoc

@@ -0,0 +1,30 @@
+[[a-blockchain-e-distribuida-e-descentralizada]]
+= A Blockchain é distribuída e descentralizada
+
+Vimos que uma {blockchain} é uma estrutura de dados confiável que só aceita inserções de dados.
+Ou seja, ela é resistente a mudanças.
+Mas, além disso, uma {blockchain} é também uma rede de computadores onde essa estrutura de dados é replicada.
+Dessa forma, sua estrutura de dados existe, distribuída, em cada um dos computadores (nós) dessa rede.
+
+O objetivo principal da distribuição de uma {blockchain} entre vários nós é impedir que mesmo sendo ela válida num único nó, ela só seja totalmente válida quando houver um {uri-consenso}[consenso] (na rede) de que suas informações também são válidas em todos os outros nós.
+Numa {blockchain}, os nós pertencentes a sua rede são responsáveis por validar dados e retransmití-los de forma que eles sejam replicados em todos os nós.
+Mais especificamente, quando dados precisam ser inseridos num bloco, todos os nós devem verificar se esses dados são válidos.
+Caso não sejam, esses dados serão descartados e não retransmitidos aos próximos nós.
+
+A validação de dados, obviamente, depende do que são esses dados.
+A primeira {blockchain} foi construída para resolver um problema complexo: a tranferência de valores.
+Dando crédito: [[a-origem-da-blockchain]]*os conceitos de {blockchain} que estamos aprendendo surgiram para fazer a moeda digital {uri-bitcoin}[Bitcoin] entrar em funcionamento*.
+Perceba que só agora estamos falando de uma das várias possibilidades de aplicação da {blockchain}.
+Apresentaremos, ainda, vários outros casos de uso de uma {blockchain}.
+
+O que diferencia a solução da {blockchain}, dada para o Bitcoin, de soluções bancárias tradicionais que resolvem esse problema, entretanto, é a descentralização.
+Detalharemos mais sobre transações, logo a frente.
+Mas, por enquanto, é importante saber que uma {blockchain}, por ser descentralizada, precisa criar algoritmos que promovam a manutenção de um consenso entre os nós.
+
+É através de consenso que uma {blockchain} identifica se uma cópia de seus dados, que está num nó, é realmente válida ou não.
+Acessando a {uri-blockchain-demo-distributed}[aba Distributed] podemos identificar que a alteração de uma das cópias da {blockchain} num dos nós é possível de ser realizada.
+E, essa alteração pode, com certeza, tornar a cópia da {blockchain} válida nesse nó.
+Como vimos, para isso ocorrer, seria necessário refazer os cálculos de `Hash` para cada bloco a partir do que for modificado.
+Mas, caso isso ocorra, outros nós da rede percebem a diferença e, automaticamente, eliminam a participação do nó que possui a {blockchain} adulterada.
+Isso é feito através de consenso.
+A rede que está certa é a rede que detém a maioria do consenso (51%).

docs/pt-br/demonstracao/o-que-e-uma-blockchain/index.adoc

@@ -0,0 +1,10 @@
+[[o-que-e-uma-blockchain]]
+= O que é uma Blockchain?
+
+:leveloffset: +1
+
+include::uma-visualizacao-grafica.adoc[]
+
+include::a-blockchain-e-distribuida-e-descentralizada.adoc[]
+
+:leveloffset: -1