# easycli - Documentação Completa

Este doc cobre tudo do nosso CLI (easycli) pra interagir com:
- EasyBRL (ERC20) – comando `coin`
- EasyToken (ERC721) – comando `token`
- Utilidades – comando `polygon`

Dica: tudo que for valor on-chain usa UNIDADES BASE (inteiro). Para o eBRL, 6 casas decimais. Ex.: 1,23 eBRL = 1_230_000.

## Pré-requisitos
- Go 1.21+
- Node RPC: `RPC_URL` ou `POLYGON_RPC_URL` (ou `AMOY_RPC_URL`)
- Endereços dos contratos: `EASY_COIN_ADDR`, `EASY_TOKEN_ADDR`
- Chave do admin: `PRIVATE_KEY` (ou `EASY_ADMIN_PRIVATE_KEY`/`EASY_ADMIM_PRIVATE_KEY`)
- Opcional: chaves do usuário de teste (não-admin): `NOT_EASY_ADMIM_PUBLIC_KEY`, `NOT_EASY_ADMIN_PRIVATE_KEY`

Arquivo .env pode ficar na raiz (../.env relativo a sdk/) ou em sdk/.env. Flags sempre sobrescrevem .env.

Evite CRLF no .env (linha do Windows). Se aparecer erro tipo `invalid hex character '\r'`, troque pra LF.

## Build e ajuda

Na pasta sdk/

```bash
go mod tidy
go build -o easycli .
./easycli --help
```

Saída global (resumo):
- Flags globais: `--rpc`, `--pk`, `--coin-addr`, `--token-addr`
- Comandos: `coin`, `token`, `polygon`

## Flags globais
- `--rpc`: URL do RPC (sobrepõe .env)
- `--pk`: chave privada do remetente (hex) para transações
- `--coin-addr`: endereço do contrato ERC20 EasyBRL
- `--token-addr`: endereço do contrato ERC721 EasyToken

Exemplo geral:
```bash
./easycli --rpc $RPC_URL --coin-addr $EASY_COIN_ADDR coin info
```

---

# Comando: polygon

## polygon create-new-address
Gera uma carteira nova.

Exemplo:
```bash
./easycli polygon create-new-address
```
Saída esperada:
```
privateKey=0x<hex>
publicKey=0x<hex>
address=0x<addr>
```

---

# Comando: coin (ERC20 EasyBRL)

## coin info
Mostra nome, símbolo, decimais, totalSupply, e paused.
```bash
./easycli --rpc $RPC_URL --coin-addr $EASY_COIN_ADDR coin info
```
Saída:
```
name=EasyBRL symbol=eBRL decimals=6 totalSupply=123456789 paused=false
```

## coin balance --address <addr>
Consulta saldo em unidades base.
```bash
./easycli coin balance --address 0xAbc...
```
Saída:
```
1000000
```

## coin transfer --to <addr> --amount <base>
Transfere tokens.
```bash
./easycli coin transfer --to 0xAbc... --amount 5000
```
Saída:
```
0x<txhash>
```

## coin approve --spender <addr> --amount <base>
Aprova o spender pra gastar seus tokens.
```bash
./easycli coin approve --spender 0xSpender... --amount 20000
```
Saída:
```
0x<txhash>
```

## coin allowance --owner <addr> --spender <addr>
Consulta allowance.
```bash
./easycli coin allowance --owner 0xOwner... --spender 0xSpender...
```
Saída:
```
20000
```

## coin transfer-from --from <addr> --to <addr> --amount <base>
Transfere usando a allowance disponível.
```bash
./easycli coin transfer-from --from 0xUser... --to 0xAdmin... --amount 5000
```
Saída:
```
0x<txhash>
```

## coin paused
Consulta se está pausado.
```bash
./easycli coin paused
```
Saída:
```
false
```

## coin pause
Pausa transferências (precisa de papel apropriado – admin/pauser).
```bash
./easycli coin pause
```
Saída:
```
0x<txhash>
```

## coin unpause
Despausa.
```bash
./easycli coin unpause
```
Saída:
```
0x<txhash>
```

## coin set-blacklist --account <addr> --status <true|false>
Configura blacklist.
```bash
./easycli coin set-blacklist --account 0xUser... --status true
```
Saída:
```
0x<txhash>
```

## coin is-blacklisted --account <addr>
Verifica blacklist.
```bash
./easycli coin is-blacklisted --account 0xUser...
```
Saída:
```
true
```

## coin mint --to <addr> --amount <base>
Mint (admin).
```bash
./easycli coin mint --to 0xUser... --amount 100000
```
Saída:
```
0x<txhash>
```

## coin burn --amount <base>
Burn do próprio saldo (admin).
```bash
./easycli coin burn --amount 10000
```
Saída:
```
0x<txhash>
```

## coin burn-from --account <addr> --amount <base>
Burn de outro (conforme regras/allowance/role).
```bash
./easycli coin burn-from --account 0xUser... --amount 1
```
Saída:
```
0x<txhash>
```

## Roles (coin)
Papéis: `DEFAULT_ADMIN_ROLE`, `PAUSER_ROLE`, `MINTER_ROLE`, `COMPLIANCE_ROLE`.

### coin grant-role --role <ROLE> --account <addr>
```bash
./easycli coin grant-role --role COMPLIANCE_ROLE --account 0xUser...
```
Saída:
```
0x<txhash>
```

### coin revoke-role --role <ROLE> --account <addr>
```bash
./easycli coin revoke-role --role COMPLIANCE_ROLE --account 0xUser...
```
Saída:
```
0x<txhash>
```

### coin has-role --role <ROLE> --account <addr>
```bash
./easycli coin has-role --role COMPLIANCE_ROLE --account 0xUser...
```
Saída:
```
true
```

### coin grant-compliance-role --account <addr>
Atalho para conceder COMPLIANCE_ROLE.
```bash
./easycli coin grant-compliance-role --account 0xUser...
```
Saída:
```
0x<txhash>
```

---

# Comando: token (ERC721 EasyToken)

## token info
```bash
./easycli --rpc $RPC_URL --token-addr $EASY_TOKEN_ADDR token info
```
Saída:
```
name=EasyToken symbol=eToken paused=false
```

## token owner-of --token-id <id>
```bash
./easycli token owner-of --token-id 1
```
Saída:
```
0xOwner...
```

## token balance --address <addr>
Quantidade de NFTs do endereço (valor inteiro).
```bash
./easycli token balance --address 0xUser...
```
Saída:
```
2
```

## token token-uri --token-id <id>
```bash
./easycli token token-uri --token-id 1
```
Saída:
```
https://example.com/doc1.json
```

## token doc-hash --token-id <id>
```bash
./easycli token doc-hash --token-id 1
```
Saída:
```
0x<64-hex>
```

## token appraisal --token-id <id>
Valor de avaliação (base units).
```bash
./easycli token appraisal --token-id 1
```
Saída:
```
1000000
```

## token set-token-uri --token-id <id> --uri <url>
Requer `METADATA_ROLE`.
```bash
./easycli token set-token-uri --token-id 1 --uri https://example.com/doc1-updated.json
```
Saída:
```
0x<txhash>
```

## token set-appraisal --token-id <id> --value <base>
Requer `APPRAISER_ROLE`.
```bash
./easycli token set-appraisal --token-id 1 --value 1200000
```
Saída:
```
0x<txhash>
```

## token safe-mint --to <addr> --uri <url> --hash <0x64hex> --value <base>
Minte um novo NFT de documento.
```bash
./easycli token safe-mint --to 0xUser... --uri https://example.com/doc1.json --hash 0x<64-hex> --value 1000000
```
Saída:
```
0x<txhash>
```

## token transfer --to <addr> --token-id <id>
Transfere seu NFT.
```bash
./easycli token transfer --to 0xTo... --token-id 1
```
Saída:
```
0x<txhash>
```

## token safe-transfer --to <addr> --token-id <id>
Versão explícita de safeTransferFrom.
```bash
./easycli token safe-transfer --to 0xTo... --token-id 1
```
Saída:
```
0x<txhash>
```

## token approve --to <addr> --token-id <id>
Aprova alguém pra esse tokenId.
```bash
./easycli token approve --to 0xSpender... --token-id 1
```
Saída:
```
0x<txhash>
```

## token set-approval-for-all --operator <addr> --approved <bool>
Aprovação por operador.
```bash
./easycli token set-approval-for-all --operator 0xOp... --approved true
```
Saída:
```
0x<txhash>
```

## token get-approved --token-id <id>
```bash
./easycli token get-approved --token-id 1
```
Saída:
```
0xApproved...
```

## token is-approved-for-all --owner <addr> --operator <addr>
```bash
./easycli token is-approved-for-all --owner 0xOwner... --operator 0xOp...
```
Saída:
```
true
```

## token paused | token pause | token unpause
```bash
./easycli token paused
./easycli token pause
./easycli token unpause
```
Saídas:
```
false
0x<txhash>
0x<txhash>
```

## token set-blacklist --account <addr> --status <bool>
```bash
./easycli token set-blacklist --account 0xUser... --status true
```
Saída:
```
0x<txhash>
```

## token is-blacklisted --account <addr>
```bash
./easycli token is-blacklisted --account 0xUser...
```
Saída:
```
true
```

## Roles (token)
Papéis: `DEFAULT_ADMIN_ROLE`, `PAUSER_ROLE`, `MINTER_ROLE`, `METADATA_ROLE`, `APPRAISER_ROLE`, `COMPLIANCE_ROLE`.

### token grant-role --role <ROLE> --account <addr>
```bash
./easycli token grant-role --role MINTER_ROLE --account 0xAdmin...
```
Saída:
```
0x<txhash>
```

### token revoke-role --role <ROLE> --account <addr>
```bash
./easycli token revoke-role --role MINTER_ROLE --account 0xUser...
```
Saída:
```
0x<txhash>
```

### token has-role --role <ROLE> --account <addr>
```bash
./easycli token has-role --role MINTER_ROLE --account 0xUser...
```
Saída:
```
false
```

### token grant-compliance-role --account <addr>
```bash
./easycli token grant-compliance-role --account 0xUser...
```
Saída:
```
0x<txhash>
```

---

# Geração de hash de documento (bytes32)
Use um SHA-256 (64 hex) e prefixe com 0x. Exemplo rápido no Linux/macOS:
```bash
echo -n "meu-doc" | sha256sum | awk '{print $1}'
# 0x<coloque-prefixo-0x-no-resultado>
```

# Dicas e solução de problemas
- Erro `invalid hex character '\r'`: seu .env está com CRLF. Troque pra LF.
- `missing address`/`invalid address`: confira EASY_COIN_ADDR/EASY_TOKEN_ADDR e se têm prefixo 0x.
- `execution reverted`: geralmente falta de role, blacklist ou paused. Verifique permissões e status.

# Testes E2E
Temos um script de teste: `sdk/test_cli.sh` que roda cenários com admin e não-admin, barra de progresso e checklist final.