spellbook
v2-2-0 Add CryptoPunks, Labels
Bienvenue dans le livre de sorts. Lancez une incantation magique pour apprivoiser la blockchain.
Spellbook est la couche d'interprétation de Dune, construite pour et par la communauté.
Spellbook est un projet dbt. Chaque modèle est une simple requête SQL avec un sucre syntaxique mineur (destiné à capturer les dépendances et à aider à construire les tables résultantes), et effectue une petite partie de la tâche consistant à transformer les enregistrements bruts et décodés en données blockchain interprétables.
Spellbook est construit pour et par la communauté, vous êtes invités à combler toutes les lacunes que vous trouvez en envoyant un PR, en créant des problèmes pour proposer de petites modifications ou suivre des bugs, ou participer à des discussions pour aider à orienter l'avenir de ce projet.
Spellbook comporte de nombreuses pièces mobiles et des principes de conception spécifiques pour contribuer à la couche d'interprétation des données de Dune. Afin de préparer les contributeurs à participer le plus efficacement possible, le répertoire de documents contient un large éventail de sujets pour répondre aux questions courantes et fournir des informations sur les raisons pour lesquelles le dépôt est configuré tel quel. Veuillez lire et vous référer à cette section lors du développement dans Spellbook et des questions se posent. L'équipe Dune établira également des liens vers ces documents pour répondre souvent aux questions, contribuer à accroître la sensibilisation et à maintenir les communications propres.
Afin de faire évoluer Spellbook, le dépôt a introduit des sous-projets pour briser un peu les lignées DBT complexes et garder les zones de concentration propres. Cela aidera également l’orchestration en aval à garder les sorts frais en production. Les sous-projets DBT dans Spellbook sont simplement plusieurs projets DBT au sein d'un seul dépôt. La structure actuelle des projets :
dbt_subprojectsdaily_spellbookhourly_spellbookdexdex ou dex_aggregator , y compris les sorts en amont pour aider à construire les sorts finaux au niveau du secteurnftnft , y compris les sorts en amont pour aider à construire les sorts finaux au niveau du secteursolanatokensPour plus d’informations sur les sous-projets, veuillez visiter cette discussion et y poser vos questions.
Vous voulez vous mettre directement au travail ? Suivez le guide ici pour commencer.
Vous n'avez pas besoin d'une configuration locale complexe pour tester les sorts contre le moteur de Dune. Une fois que vous avez envoyé un PR, notre pipeline CI l'exécutera et le testera et, si le travail se termine avec succès, vous pourrez interroger les données créées par votre PR directement depuis dune.com.
Écrivez simplement une requête comme vous le feriez pour n'importe laquelle de nos tables actives et utilisez le schéma de test pour récupérer les tables créées par votre PR.
test_schema.git_dunesql_{{commit_hash}}_{{table_name}}
Vous pouvez facilement trouver les noms exacts en consultant les journaux de l'action dbt slim ci , sous dbt run initial model(s) .
Remarque : les tables de test créées dans le pipeline CI existeront pendant environ 24 heures. Si votre table n’existe pas, déclenchez à nouveau l’exécution du pipeline et recréez la table de test.
Nous utilisons Discord pour nous connecter avec notre communauté. Rendez-vous sur la chaîne des grimoires sur Discord de Dune pour poser des questions ou demander de l'aide sur un PR particulier. Nous vous encourageons à apprendre par la pratique et à tirer parti de notre communauté dynamique pour vous aider à démarrer.
git config --global core.autocrlf true . plus d'infosVous pouvez en regarder la version vidéo si vous faites défiler un peu vers le bas.
Accédez au dépôt de livre de sorts dans votre CLI (interface de ligne de commande).
cd userdirectorygithubspellbook
# Change this to wherever spellbook is stored locally on your machine.À l'aide du fichier pip situé dans le dépôt du livre de sorts, exécutez la commande d'installation ci-dessous pour créer un pipenv.
pipenv installSi l'installation échoue, l'une des raisons probables est que notre script recherche une version statique de Python et que la probabilité d'une erreur pour une mauvaise version de Python est assez élevée. Si cette erreur se produit, vérifiez votre version de Python avec :
python --version Utilisez maintenant n'importe quel programme d'édition de texte pour remplacer la version de Python dans le fichier pip du répertoire du livre de sorts par votre version de Python. Vous devez avoir au moins Python 3.9. Si vous avez modifié la version de Python dans le fichier pip, exécutez à nouveau pipenv install .
Vous êtes maintenant prêt à activer l'environnement virtuel de ce projet. Exécutez la commande suivante pour accéder à l'environnement :
pipenv shellVous avez maintenant créé un environnement virtuel pour ce projet. Vous pouvez en savoir plus sur les environnements virtuels ici.
Dans le dépôt Spellbook, il existe plusieurs projets dbt, situés dans le répertoire racine. Accédez au projet approprié, en fonction de votre cas d'utilisation.
cd ../spellbook/dbt_subprojects/<subproject_name>/Chaque sous-projet possède son propre fichier de projet dbt avec différentes configurations. Une fois que votre CLI a accédé au répertoire de projet correct, suivez les étapes ci-dessous :
Pour nettoyer le projet dbt
dbt cleanPour extraire les dépendances du projet dbt, exécutez :
dbt depsPour compiler des modèles en SQL brut, les exécuter sur l'application dune et valider :
dbt compile Chaque sous-projet Spellbook comprend un fichier profiles.yml , qui indique à dbt comment exécuter des commandes. Le profil se trouve dans le répertoire de chaque sous-projet, comme ici. Cela ne devrait jamais avoir besoin d'être modifié, sauf si cela est intentionnel par l'équipe Dune.
Le fichier profiles.yml étant stocké dans le répertoire racine de chaque sous-projet, c'est pourquoi les utilisateurs doivent se trouver dans le répertoire racine de chaque sous-projet sur la ligne de commande pour exécuter dbt compile comme prévu.
dbt compile compilera le SQL basé sur un modèle JINJA et SQL en SQL simple qui peut être exécuté dans l'interface utilisateur de Dune. Votre répertoire de grimoire contient désormais un dossier nommé target contenant les versions SQL simples de tous les modèles de Dune. Si vous avez apporté des modifications au dépôt avant d'effectuer toutes ces actions, vous pouvez maintenant être certain qu'au moins le processus de compilation fonctionne correctement. S'il y a de grosses erreurs, le processus de compilation ne se terminera pas. Si vous n'avez pas modifié le répertoire au préalable, vous pouvez maintenant commencer à ajouter, modifier ou supprimer des fichiers dans le référentiel. Ensuite, exécutez simplement à nouveau dbt compile une fois que vous avez terminé votre travail dans le répertoire et testez les requêtes SQL en langage clair sur dune.com.
Si vous avez effectué cette installation sur votre ordinateur une fois, pour revenir dans dbt, accédez simplement au référentiel du livre de sorts, exécutez pipenv shell et vous pourrez réexécuter dbt compile .
Vous avez désormais la possibilité de compiler vos instructions de modèle dbt et vos instructions de test en SQL simple. Cela vous permet de tester ces requêtes sur l'environnement habituel de dune.com et devrait donc conduire à une meilleure expérience lors du développement de sorts. L'exécution des requêtes vous donnera immédiatement des informations sur les fautes de frappe, les erreurs logiques ou les incohérences. Cela nous aidera à déployer ces sorts plus rapidement et à éviter toute erreur potentielle.
Il y a quelques nouveaux concepts à prendre en compte lors de la création de sorts en dbt. Les plus courants que les assistants rencontreront sont les références, les sources, la fraîcheur et les tests.
Dans le corps de chaque requête, les tables sont appelées soit refs, ex {{ ref('1inch_ethereum') }} , soit sources, ex {{ source('ethereum', 'traces') }} . Les références font référence à d'autres modèles dbt et doivent faire référence au nom de fichier comme 1inch_ethereum.sql , même si le modèle lui-même est un alias. Les sources font référence à des données « brutes » ou à des tableaux/vues non générés par dbt. L'utilisation de références et de sources nous permet de créer automatiquement des arbres de dépendances.
Les sources et les modèles sont définis dans les fichiers schema.yml où les tests et autres attributs sont définis.
La meilleure pratique consiste à ajouter des tests uniques et non_null à la clé primaire pour chaque nouveau modèle. De même, un contrôle de fraîcheur doit être ajouté à chaque nouvelle source (même si nous essaierons de ne pas re-tester la fraîcheur si la source est utilisée ailleurs).
L'ajout de descriptions aux tableaux et aux colonnes aidera les utilisateurs à trouver et à utiliser vos tableaux.
models :
- name : 1inch_ethereum
description : " Trades on 1inch, a DEX aggregator "
columns :
- name : tx_hash
description : " Table primary key: a transaction hash (tx_hash) is a unique identifier for a transaction. "
data_tests :
- unique
- not_null
sources :
- name : ethereum
freshness :
warn_after : { count: 12, period: hour }
error_after : { count: 24, period: hour }
tables :
- name : tracesVoir les liens vers plus de documents sur dbt ci-dessous.
Pour générer de la documentation et l'afficher sous forme de site Web, exécutez les commandes suivantes :
dbt docs generatedbt docs serve Vous devez avoir configuré dbt avec dbt init mais vous n'avez pas besoin des informations d'identification de la base de données pour exécuter ces commandes.Consultez la documentation de dbt docs pour plus d'informations sur la manière de contribuer à la documentation.
En aperçu, vous pouvez faire des choses comme :
