easyBlockchain/doc/EASYCLI.md

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/

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:

./easycli --rpc $RPC_URL --coin-addr $EASY_COIN_ADDR coin info

---

Comando: polygon

polygon create-new-address

Gera uma carteira nova.

Exemplo:

./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.

./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

Consulta saldo em unidades base.

./easycli coin balance --address 0xAbc...

Saída:

1000000

coin transfer --to --amount

Transfere tokens.

./easycli coin transfer --to 0xAbc... --amount 5000

Saída:

0x<txhash>

coin approve --spender --amount

Aprova o spender pra gastar seus tokens.

./easycli coin approve --spender 0xSpender... --amount 20000

Saída:

0x<txhash>

coin allowance --owner --spender

Consulta allowance.

./easycli coin allowance --owner 0xOwner... --spender 0xSpender...

Saída:

20000

coin transfer-from --from --to --amount

Transfere usando a allowance disponível.

./easycli coin transfer-from --from 0xUser... --to 0xAdmin... --amount 5000

Saída:

0x<txhash>

coin paused

Consulta se está pausado.

./easycli coin paused

Saída:

false

coin pause

Pausa transferências (precisa de papel apropriado – admin/pauser).

./easycli coin pause

Saída:

0x<txhash>

coin unpause

Despausa.

./easycli coin unpause

Saída:

0x<txhash>

coin set-blacklist --account --status

Configura blacklist.

./easycli coin set-blacklist --account 0xUser... --status true

Saída:

0x<txhash>

coin is-blacklisted --account

Verifica blacklist.

./easycli coin is-blacklisted --account 0xUser...

Saída:

true

coin mint --to --amount

Mint (admin).

./easycli coin mint --to 0xUser... --amount 100000

Saída:

0x<txhash>

coin burn --amount

Burn do próprio saldo (admin).

./easycli coin burn --amount 10000

Saída:

0x<txhash>

coin burn-from --account --amount

Burn de outro (conforme regras/allowance/role).

./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 --account

./easycli coin grant-role --role COMPLIANCE_ROLE --account 0xUser...

Saída:

0x<txhash>

coin revoke-role --role --account

./easycli coin revoke-role --role COMPLIANCE_ROLE --account 0xUser...

Saída:

0x<txhash>

coin has-role --role --account

./easycli coin has-role --role COMPLIANCE_ROLE --account 0xUser...

Saída:

true

coin grant-compliance-role --account

Atalho para conceder COMPLIANCE_ROLE.

./easycli coin grant-compliance-role --account 0xUser...

Saída:

0x<txhash>

---

Comando: token (ERC721 EasyToken)

token info

./easycli --rpc $RPC_URL --token-addr $EASY_TOKEN_ADDR token info

Saída:

name=EasyToken symbol=eToken paused=false

token owner-of --token-id

./easycli token owner-of --token-id 1

Saída:

0xOwner...

token balance --address

Quantidade de NFTs do endereço (valor inteiro).

./easycli token balance --address 0xUser...

Saída:

2

token token-uri --token-id

./easycli token token-uri --token-id 1

Saída:

https://example.com/doc1.json

token doc-hash --token-id

./easycli token doc-hash --token-id 1

Saída:

0x<64-hex>

token appraisal --token-id

Valor de avaliação (base units).

./easycli token appraisal --token-id 1

Saída:

1000000

token set-token-uri --token-id --uri

Requer METADATA_ROLE.

./easycli token set-token-uri --token-id 1 --uri https://example.com/doc1-updated.json

Saída:

0x<txhash>

token set-appraisal --token-id --value

Requer APPRAISER_ROLE.

./easycli token set-appraisal --token-id 1 --value 1200000

Saída:

0x<txhash>

token safe-mint --to --uri --hash <0x64hex> --value

Minte um novo NFT de documento.

./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 --token-id

Transfere seu NFT.

./easycli token transfer --to 0xTo... --token-id 1

Saída:

0x<txhash>

token safe-transfer --to --token-id

Versão explícita de safeTransferFrom.

./easycli token safe-transfer --to 0xTo... --token-id 1

Saída:

0x<txhash>

token approve --to --token-id

Aprova alguém pra esse tokenId.

./easycli token approve --to 0xSpender... --token-id 1

Saída:

0x<txhash>

token set-approval-for-all --operator --approved

Aprovação por operador.

./easycli token set-approval-for-all --operator 0xOp... --approved true

Saída:

0x<txhash>

token get-approved --token-id

./easycli token get-approved --token-id 1

Saída:

0xApproved...

token is-approved-for-all --owner --operator

./easycli token is-approved-for-all --owner 0xOwner... --operator 0xOp...

Saída:

true

token paused | token pause | token unpause

./easycli token paused
./easycli token pause
./easycli token unpause

Saídas:

false
0x<txhash>
0x<txhash>

token set-blacklist --account --status

./easycli token set-blacklist --account 0xUser... --status true

Saída:

0x<txhash>

token is-blacklisted --account

./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 --account

./easycli token grant-role --role MINTER_ROLE --account 0xAdmin...

Saída:

0x<txhash>

token revoke-role --role --account

./easycli token revoke-role --role MINTER_ROLE --account 0xUser...

Saída:

0x<txhash>

token has-role --role --account

./easycli token has-role --role MINTER_ROLE --account 0xUser...

Saída:

false

token grant-compliance-role --account

./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:

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.