Feat/tokens metadata

.env

@@ -51,3 +51,17 @@ MAINNET_SEND_MANY_CONTRACT_ID=SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE.send-man
 
 # Override the default file path for the proxy cache control file
 # STACKS_API_PROXY_CACHE_CONTROL_FILE=/path/to/.proxy-cache-control.json
+
+# Enable token metadata processing. Disabled by default.
+# STACKS_API_ENABLE_FT_METADATA=1
+# STACKS_API_ENABLE_NFT_METADATA=1
+
+# Configure a script to handle image URLs during token metadata processing.
+# This example script uses the `imgix.net` service to create CDN URLs.
+# Must be an executable script that accepts the URL as the first program argument
+# and outputs a result URL to stdout.
+# STACKS_API_IMAGE_CACHE_PROCESSOR=./config/token-metadata-image-cache-imgix.js
+# Env vars needed for the above sample `imgix` script:
+# IMGIX_DOMAIN=https://<your domain>.imgix.net
+# IMGIX_TOKEN=<your token>
+

.eslintignore

@@ -14,3 +14,4 @@ src/tests-rosetta/
 src/tests-rosetta-cli/
 src/tests-bns/
 client/src/
+config/

.github/workflows/stacks-blockchain-api.yml

@@ -266,6 +266,43 @@ jobs:
         uses: codecov/codecov-action@v1
         if: always()
 
+  test-tokens:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Use Node.js
+        uses: actions/setup-node@v1
+        with:
+          node-version: '14.x'
+
+      - name: Install deps
+        run: npm install
+
+      - name: Setup env vars
+        run: echo "STACKS_CORE_EVENT_HOST=http://0.0.0.0" >> $GITHUB_ENV
+
+      - name: Setup integration environment
+        run: |
+          sudo ufw disable
+          npm run devenv:deploy -- -d
+          npm run devenv:logs -- --no-color &> docker-compose-logs.txt &
+
+      - name: Run tokens tests
+        run: npm run test:tokens
+
+      - name: Print integration environment logs
+        run: cat docker-compose-logs.txt
+        if: failure()
+
+      - name: Teardown integration environment
+        run: npm run devenv:stop
+        if: always()
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v1
+        if: always()
+
   build-publish:
     runs-on: ubuntu-latest
     needs:

.vscode/launch.json

@@ -143,6 +143,23 @@
       "preLaunchTask": "stacks-node:deploy-dev",
       "postDebugTask": "stacks-node:stop-dev"
     },
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Jest: Tokens",
+      "program": "${workspaceFolder}/node_modules/.bin/jest",
+      "args": [
+        "--testTimeout=3600000",
+        "--runInBand",
+        "--no-cache",
+        "--config",
+        "${workspaceRoot}/jest.config.tokens.js"
+      ],
+      "outputCapture": "std",
+      "console": "integratedTerminal",
+      "preLaunchTask": "stacks-node:deploy-dev",
+      "postDebugTask": "stacks-node:stop-dev"
+    },
     {
       "type": "node",
       "request": "launch",

config/token-metadata-image-cache-imgix.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node 
+const imgUrl = process.argv[2];
+const encodedUrl = encodeURIComponent(imgUrl);
+const [imgixDomain, imgixToken] = [process.env['IMGIX_DOMAIN'], process.env['IMGIX_TOKEN']];
+const signature = require('crypto').createHash('md5').update(imgixToken + '/' + encodedUrl).digest('hex');
+const resultUrl = new URL(encodedUrl + '?s=' + signature, imgixDomain);
+console.log(resultUrl.toString());

docs/api/tokens/get-fungible-tokens-metadata-list.example.schema.json

@@ -0,0 +1,18 @@
+{
+  "limit": 1,
+  "offset": 0,
+  "total": 500,
+  "results": [
+    {
+      "token_uri": "https://heystack.xyz/token-metadata.json",
+      "name": "Heystack",
+      "description": "Heystack is a SIP-010-compliant fungible token on the Stacks Blockchain, used on the Heystack app",
+      "image_uri": "https://heystack.xyz/assets/Stacks128w.png",
+      "image_canonical_uri": "https://heystack.xyz/assets/Stacks128w.png",
+      "tx_id": "0xef2ac1126e16f46843228b1dk4830e19eb7599129e4jf392cab9e65ae83a45c0",
+      "sender_address": "ST399W7Z9WS0GMSNQGJGME5JAENKN56D65VGMGKGA",
+      "symbol": "HEY",
+      "decimals": 5
+    }
+  ]
+}

docs/api/tokens/get-fungible-tokens-metadata-list.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "description": "List of fungible tokens metadata",
+  "title": "FungibleTokensMetadataList",
+  "type": "object",
+  "required": [
+    "results",
+    "limit",
+    "offset",
+    "total"
+  ],
+  "properties": {
+    "limit": {
+      "type": "integer",
+      "maximum": 200,
+      "description": "The number of tokens metadata to return"
+    },
+    "offset": {
+      "type": "integer",
+      "description": "The number to tokens metadata to skip (starting at `0`)"
+    },
+    "total": {
+      "type": "integer",
+      "description": "The number of tokens metadata available"
+    },
+    "results": {
+      "type": "array",
+      "items": {
+        "$ref": "../../entities/tokens/fungible-token.schema.json"
+      }
+    }
+  }
+}

docs/api/tokens/get-non-fungible-tokens-metadata-list.example.schema.json

@@ -0,0 +1,16 @@
+{
+  "limit": 1,
+  "offset": 0,
+  "total": 500,
+  "results": [
+    {
+      "token_uri": "https://pool.friedger.de/nft.json",
+      "name": "Friedger Pool",
+      "description": "Enjoying the stacking pool.",
+      "image_uri": "https://pool.friedger.de/nft.webp",
+      "image_canonical_uri": "https://pool.friedger.de/nft.webp",
+      "tx_id": "0xef2ac1126e16f46843228b1dk4830e19eb7599129e4jf392cab9e65ae83a45c0",
+      "sender_address": "ST399W7Z9WS0GMSNQGJGME5JAENKN56D65VGMGKGA"
+    }
+  ]
+}

docs/api/tokens/get-non-fungible-tokens-metadata-list.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "description": "List of non fungible tokens metadata",
+  "title": "NonFungibleTokensMetadataList",
+  "type": "object",
+  "required": [
+    "results",
+    "limit",
+    "offset",
+    "total"
+  ],
+  "properties": {
+    "limit": {
+      "type": "integer",
+      "maximum": 200,
+      "description": "The number of tokens metadata to return"
+    },
+    "offset": {
+      "type": "integer",
+      "description": "The number to tokens metadata to skip (starting at `0`)"
+    },
+    "total": {
+      "type": "integer",
+      "description": "The number of tokens metadata available"
+    },
+    "results": {
+      "type": "array",
+      "items": {
+        "$ref": "../../entities/tokens/non-fungible-token.schema.json"
+      }
+    }
+  }
+}

docs/entities/tokens/fungible-token.schema.example.json

@@ -0,0 +1,11 @@
+{
+  "token_uri": "https://heystack.xyz/token-metadata.json",
+  "name": "Heystack",
+  "description": "Heystack is a SIP-010-compliant fungible token on the Stacks Blockchain, used on the Heystack app",
+  "image_uri": "https://heystack.xyz/assets/Stacks128w.png",
+  "image_canonical_uri": "https://heystack.xyz/assets/Stacks128w.png",
+  "tx_id": "0xef2ac1126e16f46843228b1dk4830e19eb7599129e4jf392cab9e65ae83a45c0",
+  "sender_address": "ST399W7Z9WS0GMSNQGJGME5JAENKN56D65VGMGKGA",
+  "symbol": "HEY",
+  "decimals": 5
+}

docs/entities/tokens/fungible-token.schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "$id": "fungible-token-metadata",
+  "title": "FungibleTokenMetadata",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "token_uri",
+    "name",
+    "description",
+    "image_uri",
+    "image_canonical_uri",
+    "symbol",
+    "decimals",
+    "tx_id",
+    "sender_address"
+  ],
+  "properties": {
+    "token_uri": {
+      "type": "string",
+      "description": "An optional string that is a valid URI which resolves to this token's metadata. Can be empty."
+    },
+    "name": {
+      "type": "string",
+      "description": "Identifies the asset to which this token represents"
+    },
+    "description": {
+      "type": "string",
+      "description": "Describes the asset to which this token represents"
+    },
+    "image_uri": {
+      "type": "string",
+      "description": "A URI pointing to a resource with mime type image/* representing the asset to which this token represents. The API may provide a URI to a cached resource, dependending on configuration. Otherwise, this can be the same value as the canonical image URI."
+    },
+    "image_canonical_uri": {
+      "type": "string",
+      "description": "The original image URI specified by the contract. A URI pointing to a resource with mime type image/* representing the asset to which this token represents. Consider making any images at a width between 320 and 1080 pixels and aspect ratio between 1.91:1 and 4:5 inclusive."
+    },
+    "symbol": {
+      "type": "string",
+      "description": "A shorter representation of a token. This is sometimes referred to as a \"ticker\". Examples: \"STX\", \"COOL\", etc. Typically, a token could be referred to as $SYMBOL when referencing it in writing."
+    },
+    "decimals": {
+      "type": "number",
+      "description": "The number of decimal places in a token."
+    },
+    "tx_id": {
+      "type": "string",
+      "description": "Tx id that deployed the contract"
+    },
+    "sender_address": {
+      "type": "string",
+      "description": "principle that deployed the contract"
+    }
+  }
+}

docs/entities/tokens/non-fungible-token.schema.example.json

@@ -0,0 +1,9 @@
+{
+  "token_uri": "https://pool.friedger.de/nft.json",
+  "name": "Friedger Pool",
+  "description": "Enjoying the stacking pool.",
+  "image_uri": "https://pool.friedger.de/nft.webp",
+  "image_canonical_uri": "https://pool.friedger.de/nft.webp",
+  "tx_id": "0xef2ac1126e16f46843228b1dk4830e19eb7599129e4jf392cab9e65ae83a45c0",
+  "sender_address": "ST399W7Z9WS0GMSNQGJGME5JAENKN56D65VGMGKGA"
+}

docs/entities/tokens/non-fungible-token.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "$id": "non-fungible-token-metadata",
+  "title": "NonFungibleTokenMetadata",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "token_uri",
+    "name",
+    "description",
+    "image_uri",
+    "image_canonical_uri",
+    "tx_id",
+    "sender_address"
+  ],
+  "properties": {
+    "token_uri": {
+      "type": "string",
+      "description": "An optional string that is a valid URI which resolves to this token's metadata. Can be empty."
+    },
+    "name": {
+      "type": "string",
+      "description": "Identifies the asset to which this token represents"
+    },
+    "description": {
+      "type": "string",
+      "description": "Describes the asset to which this token represents"
+    },
+    "image_uri": {
+      "type": "string",
+      "description": "A URI pointing to a resource with mime type image/* representing the asset to which this token represents. The API may provide a URI to a cached resource, dependending on configuration. Otherwise, this can be the same value as the canonical image URI."
+    },
+    "image_canonical_uri": {
+      "type": "string",
+      "description": "The original image URI specified by the contract. A URI pointing to a resource with mime type image/* representing the asset to which this token represents. Consider making any images at a width between 320 and 1080 pixels and aspect ratio between 1.91:1 and 4:5 inclusive."
+    },
+    "tx_id": {
+      "type": "string",
+      "description": "Tx id that deployed the contract"
+    },
+    "sender_address": {
+      "type": "string",
+      "description": "principle that deployed the contract"
+    }
+  }
+}