restaurando a documentação dos smarts contracts do BCB

smartcontracts.md

@@ -1,58 +1,112 @@
-# Interação com os _smart contracts_ Selic
+# Interação com os _smart contracts_
 
 ## Objetivo
 
-Esta documentação tem como objetivo detalhar como será feita a interação com os smart contracts das operações que envolvem Títulos Públicos Federais tokenizados (TPFt), que estão disponíveis na rede do piloto do Real Digital Selic. 
+Esta documentação tem como objetivo explicar como será feita a interação com os _smart contracts_ que estão disponíveis na Rede do Piloto do Real Digital para uso dos ativos Real Digital e Real Tokenizado.
 
 Por se tratar de um piloto em ambiente de testes, esta documentação está sujeita a constantes evoluções que serão aqui refletidas.
 
-Serão fornecidos aos participantes do piloto a [ABI](https://docs.soliditylang.org/en/v0.8.20/abi-spec.html) de cada um dos contratos e seus respectivos endereços publicados na rede. Cada participante deve implementar, da forma que melhor entender, a sua interação com os contratos, fazendo uso de bibliotecas padrão Web3 como, por exemplo, o [Web3JS](https://web3js.readthedocs.io/en/v1.10.0/), [Web3J](https://docs.web3j.io/4.10.0/), ou frameworks como o [Hardhat](https://hardhat.org/) ou [Truffle](https://trufflesuite.com/).
+Serão fornecidos ao participante do piloto a [ABI](https://docs.soliditylang.org/en/v0.8.20/abi-spec.html) de cada um dos contratos e seus respectivos endereços publicados na rede. Cada participante deve implementar, da forma que melhor entender, a sua interação com os contratos, fazendo uso de bibliotecas padrão Web3 como, por exemplo, o [Web3JS](https://web3js.readthedocs.io/en/v1.10.0/), [Web3J](https://docs.web3j.io/4.10.0/), ou frameworks como, por exemplo, o [Hardhat](https://hardhat.org/) ou [Truffle](https://trufflesuite.com/).
 
+No piloto, todos os contratos serão implementados e publicados na rede pelo Banco Central do Brasil.
 
-## Smart Contracts
-Os contratos das operações (liquidação de oferta pública e compra e venda) que envolvem TPFt foram desenvolvidos usando como base o padrão [ERC1155](https://ethereum.org/pt/developers/docs/standards/tokens/erc-1155/), com a adição de [funções específicas de controle de acesso](./TPFtAccessControl.md). Somente participantes autorizados podem operar na rede do piloto, e é necessário realizar [habilitações](habilitacoes.md) para efetuar as operações com TPFt.
 
+## CBDC - [Real Digital](./RealDigital.md)
 
-Uma operação será identificada unicamente pelo operationId informado pelo participante. Este número será único na rede e sugere-se que seja utilizado o número da faixa do participante concatenado com a data vigente. Este formato não será validado e o operationId será utilizado para realizar a correspondência de uma operação de duplo comando.
+O CBDC (Central Bank Digital Currency) está definido no contrato chamado [RealDigital](./abi/RealDigital.json). 
 
-Os valores de preço unitário, quantidade e valor financeiro serão tratados nos contratos assumindo os últimos algarismos como casas decimais de acordo com cada tipo de atributo. Caso o atributo seja um inteiro, deve ser preenchido o número de casas decimais com zero nos últimos algarismos.
+Este contrato foi desenvolvido usando como base o padrão [ERC20](https://ethereum.org/pt/developers/docs/standards/tokens/erc-20/), com a adição de [funções específicas de controle de acesso](./CBDCAccessControl.md) e com as seguintes características:
 
-### Título Público Federal tokenizado - [TPFt](./ITPFt.md)
+* A carteira do Banco Central do Brasil é a gestora do token.
+* O símbolo do token é `BRL`.
+* Valor definido com 2 casas decimais
+* Apenas instituições detentoras de Conta Reservas ou Conta de Liquidação e o Tesouro Nacional poderão ter Real Digital em suas carteiras.
+* Cada participante deve mandar ao Banco Central do Brasil o endereço da sua carteira principal para o cadastro. Esta carteira será a carteira _default_ do participante e poderá ser posteriormente alterada através do contrato [RealDigitalDefaultAccount](./RealDigitalDefaultAccount.md). 
+* Após o cadastro inicial, o próprio participante poderá habilitar outras carteiras a receber Real Digital através do contrato [RealDigitalEnableAccount](./RealDigitalEnableAccount.md).
+* A solicitação de emissão de Real Digital será feita mediante chamada da carteira ao contrato [STR](./abi/STR.md)
 
-O TPFt está definido no contrato chamado TPFt que implementa a interface [ITPFt](./abi/ITPFt.json).
+### [Real Digital Default Account](./RealDigitalDefaultAccount.md)
 
-- O TPFt é fungível e identificado pelo seu código, sigla e data vencimento.
-- A carteira da Secretaria do Tesouro Nacional (STN) é a gestora do token.
-- Somente carteiras autorizadas podem receber TPFt.
-- Os tokens disponibilizados seguirão as [características dos Títulos Públicos Federais](https://www.bcb.gov.br/content/estabilidadefinanceira/selic/CaracteristicaTitulos.pdf).
+O contrato [RealDigitalDefaulAccount](./abi/RealDigitalDefaultAccount.json) permite ao participante trocar a sua carteira _default_, através do método `updateDefaultWallet`. 
 
-### Liquidação de oferta pública - [Operação 1002](./ITPFtOperation1002.md)
+Ainda, através do _mapping_ `defaultAccount`, é possível recuperar a carteira _default_ dos outros participantes, bastando passar como parâmetro o CNPJ8 da instituição desejada. 
 
-A liquidação de oferta pública está definida no contrato chamado TPFtOperation1002 que implementa a interface [ITPFtOperation1002](./abi/ITPFtOperation1002.json). O contrato permite transferir quantidades inteiras de TPFt da carteira _default_ da STN para a carteira _default_ de um participante cadastrado por meio do método `auctionPlacement`. A liquidação da operação é realizada com a entrega contra pagamento (DvP) e somente o Bacen pode transmitir o comando cedente dessa operação. Tanto o Bacen/STN quanto o Participante, na posição de cedente e cessionário, podem cancelar operações pendentes, desde que o `operationId` exista, o status da operação seja "LAN" ou "CON", e apenas a parte que iniciou o processo de liquidação de oferta pública pode solicitar o cancelamento. 
+A carteira _default_ será necessária para as transações de _swap_ detalhadas em seção específica de [swaps]().
 
-### Compra e venda - [Operação 1052](./ITPFtOperation1052.md)
+### [Real Digital Enable Account](./RealDigitalEnableAccount.md)
 
-A operação de compra e venda entre participantes e/ou clientes está definida no contrato chamado TPFtOperation1052 que implementa a interface [ITPFtOperation1052](./abi/ITPFtOperation1052.json). O contrato permite transferir quantidades fracionárias de TPFt entre carteiras de participantes e/ou clientes cadastrados por meio do método `trade`. A liquidação da operação é executada com a entrega contra pagamento (DvP). As partes envolvidas, sejam participantes ou clientes, na posição de cedente e cessionário, podem cancelar operações pendentes, desde que o `operationId` exista, o status da operação seja "LAN" ou "CON", e apenas a parte que iniciou o processo de liquidação da operação de compra e venda possa solicitar o cancelamento. 
+O contrato [RealDigitalEnableAccount](./abi/RealDigitalEnableAccount.json) permite ao participante habilitar ou desabilitar outras carteiras de sua posse para o recebimento de Real Digital. 
 
-### Resgate - [Operação 1012](./ITPFtOperation1012.md)
+Para habilitação deve ser utilizado o método `enableAccount`. Para desabilitação, `disableAccount`.
 
-A operação de resgate está definida no contrato de uso exclusivo do Banco Central chamado TPFtOperation1012 que implementa a interface [ITPFtOperation1012](./abi/ITPFtOperation1012.json). O contrato permite que o Tesouro Nacional realize o pagamento de resgate na data do vencimento do TPFt. A liquidação da operação é executada pagando Real Digital para o participante e emitindo Real Tokenizado para o cliente do participante. Foi implementada a baixa de TPFt, além disso, foi criado um contrato chamado TPFtRepaymentReserve. Esse contrato vai conter saldos que, por algum motivo, não foram possíveis de serem pagos em Real Digital ou Real Tokenizado ao participante ou cliente, respectivamente.
+### [STR](./STR.md)
 
-### Reserva de Resgate TPFt - [TPFtRepaymentReserve](./ITPFtRepaymentReserve.md)
+O contrato chamado [STR](./abi/STR.json) representa uma simulação do sistema STR, será por meio desse contrato que os participantes solicitarão Real Digital ao Banco Central do Brasil no âmbito do projeto Piloto.
 
-O contrato TPFtRepaymentReserve que implementa a interface [ITPFtRepaymentReserve](./abi/ITPFtRepaymentReserve.json) é responsável por armazenar os valores financeiros referente a pagamento de resgate de TPFt que não foi bem-sucedido. O contrato permite o saque dos valores para o participante em forma de Real digital e para o cliente em forma de Real Tokenizado através do método `withdraw`. Além disso, o contrato permite o saque dos valores por uma carteira de autoridade através do método `withdrawFrom`.
+Este contrato permite que qualquer participante solicite o _mint_ de Real Digital através de uma carteira previamente habilitada. 
 
-### **Importante**
+Para solicitar a emissão deve ser utilizado o método `requestToMint`.
 
-**Habilitação de carteiras para TPFt**
 
-A habilitação das carteiras de participantes e clientes nas operações dos Títulos Públicos Federais tokenizados (TPFt) é diferente da habilitação das carteiras de participantes e clientes no Real Digital. Para a carteira do participante ou do cliente realizar operações no TPFt, é preciso que o participante solicite a habilitação junto ao BACEN.
+## DVt (Depósito bancário à vista tokenizado) e MEt (Moeda eletrônica tokenizada) - [Real Tokenizado](./RealTokenizado.md)
 
-**Identificação de clientes para o TPFt**
+O Real Tokenizado está definido no contrato chamado [RealTokenizado](./abi/RealTokenizado.json). 
 
-A identificação das carteiras de clientes e participantes nos contratos dos Títulos Públicos Federais tokenizados (TPFt) é feita da seguinte forma: 
+Este contrato foi desenvolvido usando como base o padrão [ERC20](https://ethereum.org/pt/developers/docs/standards/tokens/erc-20/), com a adição de [funções específicas de controle de acesso](./CBDCAccessControl.md) e com as seguintes características:
 
-1. Carteira de cliente é identificada no cadastro do Key Dictionary. Neste caso, o pagamento do resgate é feito em Real Tokenizado;
 
-2. Carteira do participante é identificada no cadastro do Real Digital e inexistente no Key Dictionary. Neste caso, o pagamento do resgate é feito em Real Digital.
+* A primeira carteira default do participante será a gestora do token;
+* A criação e publicação do contrato na rede será feita exclusivamente pelo Banco Central do Brasil;
+* Caso seja necessário alterar a carteira gestora, deve ser feita solicitação de alteração ao Banco Central do Brasil através dos mecanismos oficiais de comunicação;
+* O símbolo do token `BRL@CNPJ8`. Exemplo `BRL@11111111`, para o Real Tokenizado da instituição '11111111';
+* Valor definido com 2 casas decimais;
+* Assim como o Real Digital, somente carteiras autorizadas podem receber Real Tokenizado;
+* O participante deve utilizar dos métodos `enableAccount` e `disableAccount` para gerenciar as carteiras permitidas.
 
+
+
+### [KeyDictionary](./KeyDictionary.md)
+
+O contrato [KeyDictionary](./abi/KeyDictionary.json) simulará um Diretório de Identificadores de Contas Transacionais ([DICT](https://www.bcb.gov.br/estabilidadefinanceira/dict)) para a transferência de Real Tokenizado. Durante o piloto, os dados de clientes, sempre fictícios, devem ser inseridos na rede para recuperação e identificação das carteiras de clientes durante as operações de _swap_ de transferência entre clientes.
+O método a ser invocado para a inserção de dados é o `addAccount`, que tem os seguintes parâmetros:
+
+* Chave, identificador único gerado pelo participante, deve ser salvo no formato hash (keccak256);
+* CPF do cliente fictício;
+* Código do participante;
+* Conta do cliente fictício;
+* Agência do cliente fictício;
+* Carteira do cliente fictício;
+* O Cnpj8 do participante;
+
+Ao iniciar uma transferência o participante poderá recuperar a carteira do destinatário através de consulta ao método `getWallet`.
+
+Ao receber uma transferência o participante recebedor poderá identificar o cliente pagador através da consulta aos métodos `getKey` e `getCustomerData`.
+
+
+## Swaps e comunicação Off-Chain
+
+Sempre que houver uma transferência de Real Tokenizado entre clientes de instituições distintas, essa transferência deve ser efetivada por meio de um contrato de _swap_ que permita a troca de Real Tokenizado, usando como reserva o Real Digital das respectivas instituições envolvidas.
+
+No momento, há três implementações disponíveis: uma que executa o _swap_ em apenas uma transação e outras duas que dependem da aprovação do recebedor para que a troca seja concluída. Todas as implementações foram efetuadas utilizando os padrões de _approve_ para o respectivo contrato de _swap_ previamente à execução da operação.
+
+O objetivo do piloto é testar formas distintas de _swap_ de forma a avaliar como podem se encaixar em diferentes negócios. Há, ainda, a possibilidade de implementação de um _swap_ que envolva a troca de informações _off-chain_.
+
+
+### [Swap One Step](./SwapOneStep.md)
+
+O contrato [SwapOneStep](./abi/SwapOneStep.json) efetua a transferência de Real Tokenizado em uma única transação atômica. Após os _approves_ das carteiras pagadoras de Real Tokenizado e Real Digital, a chamada ao `executeSwap` efetivará a destruição (`burn`) de Real Tokenizado do cliente pagador, a transferência (`transferFrom`) de Real Digital da instituição pagadora para a instituição recebedora e a emissão (`mint`) de Real Tokenizado para o cliente recebedor.
+
+
+
+### [Swap Two Steps](./SwapTwoSteps.md)
+
+O contrato [SwapTwoSteps](./abi/SwapTwoSteps.json) executa a transferência de forma atômica quando o participante recebedor confirmar a operação. Após os _approves_ das carteiras pagadoras de Real Tokenizado e Real Digital, a chamada ao `startSwap` irá gerar um evento para a instituição recebedora. A instituição recebedora avalia o crédito e confirma a transferência efetivando, assim, a operação atômica.
+
+
+### [Swap Two Steps Reserve](./SwapTwoStepsReserve.md)
+
+O contrato [SwapTwoStepsReserve](./abi/SwapTwoStepsReserve.json), assim como o [SwapTwoSteps](./abi/SwapTwoSteps.json), executa a transferência de forma atômica quando o participante recebedor confirmar a operação. Nesse contrato, entretanto, após os _approves_ das carteiras pagadoras de Real Tokenizado e Real Digital, a chamada ao `startSwap` efetivará a transferência dos tokens de Real Tokenizado e Real Digital para o contrato SwapToStepsReserve como forma de reserva e garantia de saldo, além de gerar um evento para a instituição recebedora. A instituição recebedora então avalia o crédito e confirma a transferência efetivando, assim, a operação atômica.
+
+
+
+[<<< Voltar](README.md)