inkathon
@inkathon
Este é um caldeira DAPP de pilha completa para tinta! Contratos inteligentes com um front -end integrado. Ele pode ser usado para começar rapidamente a desenvolver sua ideia de hackathon ou a andaime de um aplicativo Web3 pronto para produção.
O projeto faz parte de uma iniciativa SCIO Labs para melhorar a experiência do desenvolvedor na tinta! ecossistema e um membro orgulhoso do Aleph Zero EFP. ?
Outros projetos incluem:
create-ink-app ( em breve )ink!athon BoilerplateuseInkathon Hooks & Utility Libraryzink! Macros de contrato inteligenteParticipe da discussão em nosso grupo de telegrama
Se você deseja contribuir, leia nossas diretrizes de colaborador
Índice:
O caldeira vem com uma pequena tinta de amostra! Contrato Greeter que armazena uma message (a "saudação") e permite que qualquer pessoa a atualize. O front -end contém componentes simples da interface do usuário para conectar sua carteira e interagir com o contrato (ou seja, leia e escreva a message ). Experimente ao vivo no Inkathon.xyz.
O front-end funciona para fora da caixa, sem um nó local em execução, pois o contrato de amostra é pré-implantado em determinadas Nets de teste ao vivo (por exemplo, alephzero-testnet e shibuya ). Os metadados e endereços de implantação necessários são fornecidos sob contracts/deployments/ .
Pré-requisitos:
- Setup Node.js V18+ (recomendado via NVM com
nvm install 18)- Instale o PNPM (recomendado via Node.js Corepack ou
npm i -g pnpm)- Clone este repositório
[!IMPORTANTE]
Os usuários do Windows devem usar o WSL (recomendado) ou um shell personalizado como o Git Bash. PowerShell não é suportado.
Pré-requisitos ao usar o WSL para Linux:
- Instale o WSL e execute todos os comandos no terminal WSL
- Setup Node.js V18+ (recomendado via NVM com
nvm install 18)- Instale os seguintes pacotes NPM globalmente:
npm i -g npmnpm i -g pnpm node-gyp make- Clone este repositório no sistema de arquivos WSL (por exemplo
/home/<user>/inkathon).Dica: você pode inserir
\wsl$na barra superior do Windows Explorer para acessar visualmente o sistema de arquivos WSL.
# Install dependencies (once)
# NOTE: This automatically creates an `.env.local` file
pnpm install
# Start Next.js frontend
pnpm run dev Opcionalmente, para ativar simple-git-hooks (para linha e formatação automática ao se comprometer), você pode executar o seguinte comando uma vez: pnpm simple-git-hooks .
O arquivo contracts/package.json contém scripts abreviados para construção, teste e implantação de seus contratos.
Pré-requisitos:
- Instale a ferrugem através dos documentos do substrato (pule a seção "Compile um nó de substrato")
- Instale
cargo contract- Instale
substrate-contracts-node
# Set `contracts/` as the active working directory in your terminal
cd contracts
# Build contracts and move artifacts to `contracts/deployments/{contract}/` folders
pnpm run build
# Start local node with persistence (contracts stay deployed after restart)
# NOTE: When using Brave, shields have to be taken down for the UIs
pnpm run node
# # IMPORTANT: Open a separate terminal window and keep the node running
# Deploy the contracts on the local node
pnpm run deploy Como alternativa, você também pode implantar contratos manualmente usando contratos de interface do usuário ( pnpm contracts-ui UI) no navegador.
Abra o arquivo frontend/.env.local e defina a variável NEXT_PUBLIC_DEFAULT_CHAIN para development . Em seguida, reinicie o front -end e você poderá interagir com os contratos implantados no nó local.
Leia mais sobre variáveis de ambiente e todas as constantes de cadeia disponíveis na seção Variáveis de ambiente abaixo.
Existem vários lugares onde você precisa inserir o nome e o identificador do seu projeto. A maioria dessas ocorrências é destacada com A /* TODO */ Comentário no código. Você pode substituí-los facilmente um por um instalando o plug-in todo-tree .
Além disso, existem as seguintes ocorrências não altas:
inkathon.code-workspacepackage.json no diretório raiz, bem como nos contracts/ e frontend/ pacotes@inkathon/contracts ) definida no frontend/package.json e importada em frontend/src/deployments/deployments.ts Para substituir o contrato Greeter padrão ou adicionar um novo, você precisa fazer o seguinte:
contracts/src/contracts/Cargo.tomlcontracts/scripts/deploy.tsfrontend/src/deployments/deployments.ts função ContractIds Enum e getDeployments Adicionar scripts personalizados é útil para interagir com seus contratos ou testar certas funcionalidades. Portanto, basta duplicar e reutilizar o arquivo contracts/scripts/script.template.ts e executá-lo via pnpm run script <script-name> . Este comando executará o arquivo TypeScript diretamente via tsx .
Para scripts gerais, a mesma variável de ambiente inicialização e configuração se aplica conforme descrito abaixo na seção de implantação (por exemplo, para alterar a rede de destino).
contracts/ e frontend/ diretórios como pacotes.pnpm ou yarn@stable (leia mais na seção Perguntas frequentes abaixo)cargo-contract , substrate-contracts-nodepolkadot-js , useInkathon React Hooks & Utility Library (alternativamente: useInk )shadcn/ui , tailwindcsseslint , prettier , simple-git-hooks , lint-stagedtypechain-polkadotAs bibliotecas de estilo, linhagem e formatação podem ser totalmente descartadas ou substituídas por alternativas.
Abaixo, você encontra exemplos ao vivo que usam este caldeira ou têm uma configuração semelhante inspirada nele:
A rotação de uma implantação via Vercel é bastante direta, pois as configurações necessárias já estão configuradas no vercel.json . Se você ainda não clonou o repositório, também poderá usar o botão de implantação abaixo para criar um novo repositório a partir deste modelo.
Como alternativa, você também pode usar o DockerFiles fornecido para implantar para qualquer provedor de hospedagem de sua escolha. Leia mais aqui.
Todas as variáveis de ambiente são importadas do process.env no frontend/src/config/environment.ts e reexportadas a partir daí. Para melhorar a segurança do tipo, sempre importe variáveis de ambiente de @/config/environment e nunca diretamente do process.env .
| Variáveis de ambiente | Valores padrão | Descrição |
|---|---|---|
NEXT_PUBLIC_DEFAULT_CHAIN *️⃣ | ️ alephzero-testnet | A rede (cadeia baseada em substrato) a que o front-end deve se conectar por padrão e quais artefatos de implantação de contrato importar. |
NEXT_PUBLIC_PRODUCTION_MODE | false | Bandeira booleana opcional para diferenciar o ambiente de produção (por exemplo, SEO ou análise). |
NEXT_PUBLIC_URL | http://localhost:3000 | String opcional que define o URL base do front-end (será inferido automaticamente das variáveis de ambiente de vercel). |
NEXT_PUBLIC_SUPPORTED_CHAINS | - | Matriz opcional com identificação de rede (por exemplo, ["alephzero-testnet", "shibuya"] ) que são suportados pelo front-end, se o DAPP for suposto ser multi-cadeia . |
*️⃣ Necessário
Um elemento -chave, tornando este caldeira tão flexível é o uso de variáveis de ambiente para configurar a rede ativa no front -end. Isso é feito configurando a variável NEXT_PUBLIC_DEFAULT_CHAIN no arquivo frontend/.env.local , ou nas configurações de implantação, respectivamente.
Se sua rede não for fornecida pela Biblioteca use-inkathon , você poderá adicioná-la manualmente criando um novo objeto SubstrateChain . Se você acha que está faltando uma cadeia, abra um problema ou relações públicas.
Importante
Todas as constantes de cadeia suportadas podem ser encontradas aqui no repositório scio-labs/use-inkathon .
Na seção de início acima, já implantamos o contrato de Greeter amostra em um nó local. Para segmentar uma rede ao vivo, podemos usar a variável de ambiente CHAIN ao executar o script deploy .
CHAIN=alephzero-testnet pnpm run deploy Além disso, os arquivos de ambiente carregados dinamicamente com a Convenção de Nomeação .env.{chain} podem ser usados para adicionar configuração adicional sobre a conta implantadora.
# .env.alephzero-testnet
ACCOUNT_URI=bottom drive obey lake curtain smoke basket hold race lonely fit walk//AliceAo executar o mesmo script novamente, esta conta implementadora definida será usada para assinar o extrínseco.
Aviso
Esses arquivos são gitignados por padrão, mas você ainda deve ser mais cauteloso ao adicionar informações confidenciais a eles.
Pode ser útil desenvolver no VSCode, abrindo o arquivo de espaço de trabalho inkathon.code-workspace em vez do diretório simples. Essa abordagem oferece várias vantagens, como seções no File Explorer, ou ações de atalho para abrir o terminal no diretório correto.
Considere instalar a extensão zoma.vscode-auto-open-workspace para abrir automaticamente o arquivo da área de trabalho ao abrir o diretório.
Além disso, os plug -ins VSCode listados abaixo são recomendados, pois podem ser muito úteis ao trabalhar com este boilerplate.
| Nome do plug -in | Descrição |
|---|---|
dbaeumer.vscode-eslint | Adiciona suporte ao editor ESLint. |
esbenp.prettier-vscode | Adiciona suporte do editor mais bonito. |
bradlc.vscode-tailwindcss | Adiciona suporte do editor Tailwindcss. |
rust-lang.rust-analyzer | Adiciona suporte à linguagem de ferrugem. |
ink-analyzer.ink-analyzer | Adiciona tinta! Suporte ao idioma. |
tamasfe.even-better-toml | Adiciona suporte de arquivo .toml . |
gruntfuggly.todo-tree | Liste todos TODO comentários para o seu espaço de trabalho. |
wayou.vscode-todo-highlight | Destaca os comentários TODO em seu espaço de trabalho. |
mikestead.dotenv | Adiciona sintaxe destaque para arquivos .env . |
A bebida! A CLI é uma ferramenta conveniente de linha de comando que ajuda você a brincar com sua tinta! contratos sem configurar um nó local.
drink-cli via cargo install drink-cli --force --locked .pnpm run build .pnpm run drink-cli <contract-name> . Em seguida, basta usar o comando help para ver todos os comandos disponíveis e começar a interagir com o seu contrato. Por exemplo, você pode implantar o contrato de exemplo saudável por meio d --constructor default ou d "Hello World" .
Para os espaços de trabalho Monorepo, o PNPM é provavelmente a escolha mais rápida e confiável. Ao usá -lo, é fortemente recomendado que todos na equipe o usem. Nenhuma instalação deve ser executada nem outros arquivos de bloqueio devem ser comprometidos.
Como alternativa, o fio também é suportado e pode ser usado para instalação. Advertências ao usar fios:
yarn.lock devem ser comprometidos em vez de arquivos .pnpm-lock.yaml .pnpm ainda é usada em muitos scripts package.json , então eles teriam que ser ajustados manualmente.[!IMPORTANTE]
Como o NPM não possui suporte para o protocolo de importaçãoworkspace, ele não é compatível com o Ink! Athon.
Às vezes, o Next.js não recebe alterações (ou seja, criações de arquivos) nos contracts/deployments/{contract}/ pastas corretamente. Por exemplo, quando você acabou de implantar em um nó local pela primeira vez e define o .env.local do front -end para se conectar à rede development .
Para corrigir isso, você pode excluir o cache de construção no frontend/.next . Atualmente, esta é a única solução e forçará a Next.js a reconstruir o projeto e pegar os novos arquivos.
[!OBSERVAÇÃO]
Para evitar esse comportamento, o arquivocontracts/package.jsoncontém um pequeno scriptpostinstallque cria um arquivodevelopment.tsvazio. Se não existir.
Atualmente, oferece estilo através das seguintes opções prontas para uso:
className e *.module.(s)css .[! Info]
Este caldeira tenta permanecer como não opinonado em relação ao estilo, o que significa que você pode usar qualquer biblioteca de estilo ou componente.
Com typechain-polkadot , os tipos para cada contrato (arquivos de texto datilografado) são criados após a construção (através do comando build Script ou build-all.sh ). Você pode suprimir esse comportamento passando --skip-types .
Eles são armazenados sob contracts/typed-contracts/ e importados diretamente do front-end. Em seguida, através do novo gancho useRegisteredTypedContract de instâncias de useInkathon com API predefinida, endereço de contrato dependente de rede e assinante injetado estão sendo criados. Consulte greeter-contract-interactions.tsx por exemplo.
