Avançar para o conteúdo principal

react-celo

A maneira mais fácil de acessar ContractKit em suas aplicações React.

react-celo​

A maneira mais fácil de acessar [Celo](https://www. npmjs. com/package/@celo/contractkit) em suas aplicações React 🔥. react-celo é um React hook para gerenciar o acesso ao Celo com um sistema modal interno para conectar à carteira de usuários escolhida.

Agora seu DApp pode ser disponibilizado para todos no ecossistema Celo desde usuários da Valora a usuários de Ledger auto-privados.

Por padrão, o react-celo é estilizado para que você possa soltá-lo em seu aplicativo e pronto, no entanto, é totalmente personalizável para que você possa manter um UX consistente em todo o aplicativo.

Tabela de conteúdos​

Instalar​

yarn add @celo/react-celo @celo/contractkit

Carteiras suportadas​

  • Celo Dance
  • Celo Extension Wallet (Metamask fork)
  • Celo Terminal
  • Celo Wallet
  • Ledger
  • MetaMask
  • Chave privada em texto simples
  • Omni
  • Valora
  • WalletConnect

Utilização Básica​

Envolva seu aplicativo com o CeloProvider​

react-celo usa Context.Provider sob o hood para injetar estado em todo o aplicativo. Você precisa ter certeza de que sua aplicação esteja envolvida com o provedor para poder acessar todos os provedores de react-celo.

import { CeloProvider } from "@celo/react-celo";
import "@celo/react-celo/lib/styles.css";

function WrappedApp() {
  return (
    <CeloProvider
      dapp={{
        name: "My awesome dApp",
        description: "My awesome description",
        url: "https://example.com",
      }}
    >
      <App />
    </CeloProvider>
  );
}

function App() {
  // your application code
}

Carteira padrão e personalização​

react-celo fornece uma lista de carteiras padrão (CeloExtensionWallet, Injetada, Ledger, MetaMask, PrivateKey (somente dev) e WalletConnect). Ele pode ser configurado como mostrado abaixo.

<CeloProvider
  dapp={{
    name: "My awesome dApp",
    description: "My awesome description",
    url: "https://example.com",
  }}
  connectModal={{
    // This options changes the title of the modal and can be either a string or a react element
    title: <span>Connect your Wallet</span>,
    providersOptions: {
      // This option hides specific wallets from the default list
      hideFromDefaults: [
        SupportedProvider.MetaMask,
        SupportedProvider.PrivateKey,
        SupportedProvider.CeloExtensionWallet,
        SupportedProvider.Valora,
      ],

      // This option hides all default wallets
      hideFromDefaults: true,

      // This option toggles on and off the searchbar
      searchable: true,
    },
  }}
>
  <App />
</CeloProvider>

Você também pode adicionar novas carteiras personalizadas que não existem no registro ou não estão em nossos padrões. Por enquanto, só suportamos carteiras personalizadas que implementam o protocolo de walletconnect, mas mais podem vir no futuro. No exemplo abaixo, estamos ocultando todas as carteiras, exceto uma nova carteira personalizada.

<CeloProvider
  dapp={{
    name: "My awesome dApp",
    description: "My awesome description",
    url: "https://example.com",
  }}
  // Use the theme to customize the colors.
  // If you provide a theme, you must provide all values below!
  theme={{
    primary: "#6366f1",
    secondary: "#eef2ff",
    text: "#000000",
    textSecondary: "#1f2937",
    textTertiary: "#64748b",
    muted: "#e2e8f0",
    background: "#ffffff",
    error: "#ef4444",
  }}
  connectModal={{
    title: <span>Connect your ExampleWallet</span>,
    providersOptions: {
      hideFromDefaults: true,
      additionalWCWallets: [
        // see https://github.com/WalletConnect/walletconnect-registry/#schema for a schema example
        {
          id: "example-wallet",
          name: "Example Wallet",
          description: "Lorem ipsum",
          homepage: "https://example.com",
          chains: ["eip:4220"],
          // IMPORTANT
          // This is the version of WC. Suportamos apenas a versão 1 no momento.
          versions: ["1"],
          logos: {
            sm: "https://via.placeholder.com/40/000000/FFFFFF",
            md: "https://via.placeholder.com/80/000000/FFFFFF",
            lg: "https://via.placeholder.com/160/000000/FFFFFF",
          },
          app: {
            browser: "...",
            ios: "...",
            android: "...",
            mac: "...",
            windows: "..",
            linux: "...",
          },
          mobile: {
            native: "...",
            universal: "...",
          },
          desktop: {
            native: "...",
            universal: "...",
          },
          metadata: {
            shortName: "...",
            colors: {
              primary: "...",
              secondary: "...",
            },
          },
          responsive: {
            mobileFriendly: true,
            browserFriendly: true,
            mobileOnly: false,
            browserOnly: false,
          },
        },
      ],
    },
  }}
>
  <App />
</CeloProvider>

Solicitar que os usuários conectem a sua carteira​

react-celo fornece uma função de connect que abrirá uma lista de carteiras com as quais seu usuário pode se conectar.

import { useCelo } from "@celo/react-celo";

function App() {
  const { connect, address } = useCelo();

  return (
    <>
      {address ? (
        <div>Connected to {address}</div>
      ) : (
        <button onClick={connect}>Connect wallet</button>
      )}
    </>
  );
}

Após se conectar a uma conta, a propriedade address será definida.

Use ContractKit para ler os dados em cadeia​

Agora que nos conectamos a uma conta e temos o endereço de usuários, podemos usar o kit `` para consultar dados on-chain:

import { useCelo } from '@celo/react-celo';

function App() {
  const { kit, address } = useCelo();

  async function getAccountSummary() {
    const accounts = await kit.contracts.getAccounts();
    await accounts.getAccountSummary(address);
  }

  return (
    ...
  )
}

Acessando contas de usuário​

O maior problema ao desenvolver DApps é garantir uma experiência de nível Web2, enquanto gerencia o flaky e, muitas vezes, a natureza lenta das blockchains. Para esse fim, nós projetamos react-celo de uma maneira de abstrair a maior parte da dor.

Inicialmente conectar a uma conta de usuários é uma coisa, manipulado pela função de connect que acabamos de mencionar. No entanto, assim que um usuário tiver se conectado ao seu DApp uma vez que pudermos tornar a experiência mais agradável para eles em visitas de repetição.

Última conta conectada​

react-celo irá lembrar o último endereço conectado de um usuário quando ele voltar ou atualizar seu DApp. Certifique-se de que ao desenvolver seu DApp nada muda na interface do usuário, independentemente de o usuário ter ou não um conjunto de propriedades de kit.defaultAccount.

import { useCelo } from "@celo/react-celo";

const { address } = useCelo();

Obtenha uma conta conectada​

Quando um usuário atualiza ou navega de volta à sua página, ele pode não ter mais uma conta conectada. No entanto, nós não precisamos incentivá-los a logar novamente, apenas para ver a página, isso só pode ser feito ao fazer uma ação.

Para essa funcionalidade temos os métodos de performActions e getConnectedKit. O uso se parece um pouco com isso para getConnectedKit:

import { useCelo } from "@celo/react-celo";

function App() {
  const { getConnectedKit } = useCelo();

  async function transfer() {
    const kit = await getConnectedKit();
    const cUSD = await kit.contracts.getStableToken();
    await cUSD.transfer("0x...", 10000).sendAndWaitForReceipt();
  }

  return <button onClick={transfer}>Transfer</button>;
}

e isso para performActions:

import { useCelo } from "@celo/react-celo";

function App() {
  const { performActions } = useCelo();

  async function transfer() {
    await performActions(async (kit) => {
      const cUSD = await kit.contracts.getStableToken();
      await cUSD.transfer("0x...", 10000).sendAndWaitForReceipt();
    });
  }

  return <button onClick={transfer}>Transfer</button>;
}

O método performActions também cuidará de exibir um modal para o usuário, dizendo para ele confirmar quaisquer ações em sua carteira conectada.

Gerenciamento de rede​

react-celo fornece uma variávelnetworke uma função updateNetwork que você pode usar para exibir a rede atualmente conectada, bem como mudar para uma diferente. (Alfajores, Baklava ou Mainnet).

Se você prefere que seu DApp acesse apenas uma rede específica (talvez você esteja implantando seu site testnet em https://test-app.dapp. Nome e sua versão mainnet em https://app.dapp. O nome) que você pode passar a rede que deseja usar como variável no provedor com o qual você implementa seu aplicativo com:

Você também pode passar em uma propriedade network para o CeloProvider como a rede inicial padrão

walletChainId vs network​

useCelo retorna duas propriedades. rede, um objeto com nome, chainId e url rpc é com qual cadeia / rede o dapp está se comunicando. walletChainId é a chainID à qual a carteira/assinante está conectada (assumindo que este é um conceito que tem) ou será nulo, a menos que o modo de rede manual esteja ativado, eles eventualmente serão consistentes ou walletChainId será nulo.

import { CeloProvider, Alfajores, NetworkNames } from '@celo/react-celo';

function WrappedApp({ Component, pageProps }) {
  return (
    <CeloProvider
      ...
      networks={[Alfajores]}
      network={{
        name: NetworkNames.Alfajores,
        rpcUrl: 'https://alfajores-forno.celo-testnet.org',
        graphQl: 'https://alfajores-blockscout.celo-testnet.org/graphiql',
        explorer: 'https://alfajores-blockscout.celo-testnet.org',
        chainId: 44787,
      }}
    >
      <App />
    </CeloProvider>
  );
}

function App () {
  ...
}

Certifique-se de verificar o aplicativo de exemplo react-celo para uma demonstração de como o gerenciamento de redes funciona com mais profundidade. Geralmente você vai querer mostrar uma lista suspensa para os usuários, permitindo-lhes selecionar a rede a se conectar.

import { useCelo } from "@celo/react-celo";

function App() {
  const { network, updateNetwork } = useCelo();

  return <div>Currently connected to {network}</div>;
}

Estendendo Redes Suportadas​

Por padrão Use-Contractkit suporta apenas redes de Blockchain de Celo. No entanto, você pode estender isso para incluir outras cadeias que você escolher como Ethereum, Polygon, Avalanche etc Passando sua matriz de Networks para CeloProvider. Note que este recurso é considerado experimental e funciona melhor com carteiras como Metamask.

Modo de rede manual​

Opte por sair do React-Celo trocando automaticamente em qual rede o dapp / carteira estão ligadas. walletChainId pode ser diferente do dapp network.chainId. Você PRECISA usar updateNetwork para definir a cadeia desejada neste caso.

Ajusta FeeCurrency​

react-celo fornece uma variável feeCurrency e uma função updateFeeCurrency que você pode usar para exibir a Moeda Feira atualmente selecionada (cUSD, CELO, cEUR). A feeCurrency também pode ser passada para o componente do provedor. Valores válidos são CeloContract.GoldToken, CeloContract.StableToken, CeloContract.StableTokenEUR. O CeloContract pode ser importado assim:

import { CeloTokenContract } from '@celo/contractkit'

Temas e Modo escuro​

Atualmente, react-celo suporta o modo escuro e claro (também conhecido como padrão), para usar o modal no modo escuro basta adicionar a classe tw-dark na raiz <html /> da página da web.

Se você não tiver um estilo padrão ao seu gosto, você pode fornecer um objeto de tema definido como tal. Você pode fazê-lo durante a configuração do seu dapp, no nível Provider. Ou em tempo real (digamos, se seus usuários podem alterar o tema do seu dapp), através de updateTheme.

interface Theme {
  primary: string;
  secondary: string;
  text: string;
  textSecondary: string;
  textTertiary: string;
  muted: string;
  background: string;
  error: string;
}

Log e depuração​

Nós logamos por padrão debug ou superior no modo de desenvolvimento. É determinado pelas suas variáveis de ambiente: definindo DEBUG como true ou definindo NODE_ENV para outra como production). No modo de production , registramos apenas erro.

Mas você pode fornecer seu próprio registrador ao nível do provedor. Ele deve implementar nossa ILogger interface que se parece com isso:

interface ILogger {
  debug(...args: unknown[]): void;
  log(...args: unknown[]): void;
  warn(...args: unknown[]): void;
  error(...args: unknown[]): void;
}

Desenvolvimento​

Para executar todos os pacotes localmente de uma vez, basta clonar este repositório e executar:

yarn;
yarn build;  #only needs to be run the first time
yarn dev;

Um servidor de recarregamento quente deve aparecer no localhost:3000, é exatamente o mesmo que em react-celo-c-labs.vercel.app.

Como alternativa, você pode executar individualmente react-celo e o app example em paralelo.

Para isso, você ainda precisa executar yarn na raiz.

Então, você pode executar react-celo em uma aba:

cd packages/react-celo
yarn dev

e execute o aplicativo example em outro:

cd packages/example
yarn dev

Suporte​

Algum problema com qualquer coisa relacionada ao react-celo? Vá para o GitHub Discussions ou celo-org canal e peça ajuda a qualquer momento.

Guias​

Informações mais especializadas de uso pode ser encontrada em nossos Guias