Ir al contenido principal

React-Celo

La manera más fácil de acceder a ContractKit en tus aplicaciones React.

React-Celo​

La manera más fácil de acceder a Celo en tus aplicaciones React 🔥. react-celo es un React hook para administrar el acceso a Celo con un sistema modal integrado sin cabecera para conectarse a la billetera de su elección.

Ahora su DApp puede ser puesto a disposición de todos en el ecosistema de Celo, desde usuarios de Valora hasta usuarios Ledger autocustodiados.

Por defecto, react-celo está diseñado para que puedas colocarlo en tu aplicación y listo, sin embargo, es totalmente personalizable para que puedas mantener una UX consistente en toda tu aplicación.

Tabla de Contenidos​

Instalar​

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

Billeteras Soportadas​

  • Celo Dance
  • Celo Extension Wallet (Metamask fork)
  • Celo Terminal
  • Celo Wallet
  • Ledger
  • MetaMask
  • Clave privada de texto plano
  • Omni
  • Valora
  • WalletConnect

Uso Básico​

Envuelve tu aplicación con CeloProvider​

react-celo usa React's Context.Provider bajo la capa para inyectar estado a través de la aplicación. Debe asegurarse de que su aplicación está envuelta con el proveedor para poder acceder a todos los bienes que react-celo proporciona.

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
}

Billeteras predeterminadas y personalización​

react-celo proporciona una lista de billeteras por defecto (CeloExtensionWallet, Injected, Ledger, MetaMask, PrivateKey (sólo desarrollo) y WalletConnect). Puede configurarse como se muestra a continuación.

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

También puede añadir nuevas billeteras personalizadas que no existen en el registro o que no están en nuestros valores predeterminados. Por ahora, sólo apoyamos las billeteras personalizadas que implementan el protocolo de walletconnect, pero más pueden venir en el futuro. En el ejemplo de abajo, estamos ocultando todas las billereas excepto una nueva billetera personalizada.

<CeloProvider
  dapp={{
    name: "My awesome dApp",
    description: "My awesome description",
    url: "https://example.com",
  }}
  // Utiliza el tema para personalizar los colores.
  // Si proporciona un tema, debe proporcionar todos los valores debajo!
  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. Sólo soportamos la versión 1 en este 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>

Pedir a los usuarios que conecten su billetera​

react-celo proporciona una función connect que abrirá un modal con una lista de billeteras a las que su usuario puede 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>
      )}
    </>
  );
}

Después de conectar a una cuenta se establecerá la propiedad dirección.

Usar ContractKit para leer datos en cadena​

Ahora que hemos conectado a una cuenta y tenemos la dirección del usuario, podemos utilizar el kit para consultar datos en cadena:

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 (
    ...
  )
}

Accediendo a cuentas de usuario​

El mayor problema al desarrollar DApps es asegurar una experiencia de nivel Web2 mientras se gestiona la naturaleza defectuosa y a menudo lenta de blockchains. Para ello, hemos diseñado react-celo de una manera que abstrae la mayor parte de ese dolor.

Conectar inicialmente a la cuenta de un usuario es una cosa, manejada a través de la función connect que acabamos de mencionar. Sin embargo, una vez que un usuario se ha conectado a tu DApp podemos hacer la experiencia más agradable para ellos en visitas repetidas.

Última cuenta conectada​

react-celo recordará la última dirección conectada de un usuario cuando vuelva a su aplicación o actualice su DApp. Asegúrese de que al desarrollar su DApp nada cambia en la interfaz de usuario si el usuario tiene o no una propiedad kit.defaultAccount.

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

const { address } = useCelo();

Obtener una cuenta conectada​

Cuando un usuario refresca o navega de vuelta a tu página, puede que ya no tenga necesariamente una cuenta conectada, sin embargo no deberíamos necesitar pedirle que se conecte de nuevo sólo para ver la página, eso sólo se puede hacer al realizar una acción.

Para esa funcionalidad tenemos los métodos performActions y getConnectedKit. El uso se parece un poco a esto 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>;
}

y esto 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>;
}

El método performActions también se encargará de mostrar un modal al usuario diciéndole que confirme cualquier acción en su billetera conectada.

Administración de redes​

react-celo proporciona una variable network y una función updateNetwork que puede utilizar para mostrar la red conectada actualmente, así como para cambiar a otra diferente (por ejemplo, Alfajores, Baklava o Mainnet).

Si prefieres que tu DApp solo acceda a una red específica (tal vez estás implementando tu sitio web de testnet en https://test-app.dapp. el nombre y la versión del mainnet en https://app.dapp. ame) puede pasar la red que desea utilizar como variable al proveedor con el que envuelve su aplicación:

También puede pasar un accesorio de network al CeloProvider como la red inicial predeterminada

walletChainId vs red​

useCelo devuelve dos propiedades. red, un objeto con un nombre, un chainId y una url rpc. es con qué cadena o red se está comunicando el dapp. walletChainId es el código de cadena al que está conectado la billetera/firma (suponiendo que este es un concepto que tiene uno) o será nulo. a menos que el modo de red manual esté habilitado, estos serán consistentes o 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 () {
  ...
}

Asegúrese de comprobar la aplicación de ejemplo de react-celo para un escaparate de cómo la administración de red funciona en mayor profundidad. Normalmente querrás mostrar un menú desplegable a tus usuarios permitiéndoles seleccionar la red a la que conectar.

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

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

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

Extendiendo redes soportadas​

Por defecto Use-Contractkit sólo soporta redes de Celo Blockchain. Sin embargo, puedes extender esto para incluir otras cadenas que elijas como Ethereum, Polygon, Avalanche etc pasando su array de Network en CeloProvider. Tenga en cuenta que esta característica se considera experimental y funciona mejor con billeteras como Metamask.

Modo de red manual​

Optar por que React-Celo no cambie automáticamente la red en la que está la dapp / wallet. walletChainId podría ser diferente a la network.chainId de dapp. DEBES usar updateNetwork para establecer la cadena deseada en este caso.

Ajustar FeeCurrency​

react-celo proporciona una variable feeCurrency y una función updateFeeeCurrency que puede utilizar para mostrar la feeCurrency seleccionada actualmente (cUSD, CELO, CSLO). La feeCurrency también se puede pasar al componente proveedor. Los valores válidos son CeloContract.GoldToken, CeloContract.StableToken, CeloContract.StableTokenEUR. CeloContract puede importarse así:

import { CeloTokenContract } from '@celo/contractkit'

Temas y modo oscuro​

Actualmente react-celo soporta modo oscuro y modo claro (también conocido por defecto) a través del ajuste de la caja para usar la modal en modo oscuro, simplemente añade la clase tw-dark a la raíz <html /> etiqueta de la página web.

Si los estilos por defecto no son a tu gusto, puedes proporcionar un objeto de tema definido como tal. Puedes hacerlo durante la configuración de tu dapp, en el nivel de Provider. O sobre la marcha (digamos, si tus usuarios pueden cambiar el tema de tu dapp), a través de updateTheme.

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

Registro y depuración​

Registramos por defecto debug o superior en modo desarrollo. Se determinan las variables de entorno: estableciendo DEBUG a true o ajustando NODE_ENV a algo más que production). En el modo de producción, solo registramos error.

Pero usted es bienvenido a proporcionar su propio registrador a nivel de proveedor. Debería implementar nuestra interfaz ILogger que se ve así:

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

Desarrollo​

Para ejecutar todos los paquetes localmente a la vez, simplemente clone este repositorio y ejecute:

yarn;
yarn build;  #sólo necesita ejecutarse la primera vez
yarn dev;

Un servidor de recarga en caliente debería aparecer en localhost:3000, es exactamente lo mismo que en react-celo-c-labs.vercel.app.

Alternativamente, puedes ejecutar react-celo individualmente y la aplicación example en paralelo.

Para eso, todavía necesitas ejecutar yarn en la raíz.

Luego, puedes ejecutar react-celo en una pestaña:

cd packages/react-celo
yarn dev

y ejecuta la aplicación example en otra:

cd packages/example
yarn dev

Soporte​

¿Luchando con algo relacionado con react-celo? Salta al GitHub Discussions o celo-org discord channel y pide ayuda en cualquier momento.

Guías​

Puedes encontrar más información de casos de uso especializado en nuestras Guías