@europeum-ebsi/cli 0.0.0 → 1.0.0-rc.0

package/src/commands/contracts-registry.ts

@@ -0,0 +1,156 @@
+import type { CommandDescriptor } from "./registry.ts";
+
+import { getClient, unwrap } from "../api/fetch.ts";
+import { q } from "../api/params.ts";
+import { contractAddressOption } from "../ledger/registries.ts";
+import { requiredArg } from "./shared/args.ts";
+
+const PAGINATION_OPTIONS = [
+  {
+    description: "Cursor for pagination (page[after])",
+    flags: "--page-after <cursor>",
+  },
+  {
+    description: "Maximum number of items per page (page[size])",
+    flags: "--page-size <n>",
+  },
+];
+
+// contracts-registry has no local ABI/write path (see src/ledger/registries.ts), so unlike the
+// other domains there's no shared `REGISTRIES[...].addressEnvKey` to reuse here — these mirror
+// the API's own two distinct config keys for this domain
+// (api/src/config/configuration.ts: PROXY_FACTORY_CONTRACT_ADDRESS / PROXY_TEMPLATES_REGISTRY_CONTRACT_ADDRESS).
+const { option: CONTRACTS_ADDRESS_OPTION, resolve: contractsContractAddress } =
+  contractAddressOption(
+    "PROXY_FACTORY_CONTRACT_ADDRESS",
+    `Contract address to query. Defaults to $PROXY_FACTORY_CONTRACT_ADDRESS if set, otherwise the API's configured default.`,
+  );
+
+const { option: TEMPLATES_ADDRESS_OPTION, resolve: templatesContractAddress } =
+  contractAddressOption(
+    "PROXY_TEMPLATES_REGISTRY_CONTRACT_ADDRESS",
+    `Contract address to query. Defaults to $PROXY_TEMPLATES_REGISTRY_CONTRACT_ADDRESS if set, otherwise the API's configured default.`,
+  );
+
+export const contractsRegistryCommands: CommandDescriptor[] = [
+  {
+    args: [],
+    group: "Contracts Registry",
+    async handler(_args, opts, config) {
+      const client = getClient(config);
+      const result = await client.GET("/contracts-registry/contracts", {
+        params: {
+          query: q({
+            contractAddress: contractsContractAddress(opts),
+            "page[after]": opts["pageAfter"]
+              ? Number(opts["pageAfter"])
+              : undefined,
+            "page[size]": opts["pageSize"]
+              ? Number(opts["pageSize"])
+              : undefined,
+          }),
+        },
+      });
+      return unwrap(result);
+    },
+    id: "contracts-registry.contracts.list",
+    options: [...PAGINATION_OPTIONS, CONTRACTS_ADDRESS_OPTION],
+    segments: ["contracts-registry", "contracts", "list"],
+    summary: "List smart contracts registered in the EBSI Contracts Registry",
+  },
+
+  {
+    args: [
+      {
+        description: "Contract address (hex)",
+        example: "0x1234abcd...",
+        name: "address",
+        required: true,
+      },
+    ],
+    group: "Contracts Registry",
+    async handler(args, opts, config) {
+      const client = getClient(config);
+      const result = await client.GET(
+        "/contracts-registry/contracts/{address}",
+        {
+          params: {
+            path: { address: requiredArg(args, "address") },
+            query: q({ contractAddress: contractsContractAddress(opts) }),
+          },
+        },
+      );
+      return unwrap(result);
+    },
+    id: "contracts-registry.contracts.get",
+    options: [CONTRACTS_ADDRESS_OPTION],
+    segments: ["contracts-registry", "contracts", "get"],
+    summary: "Get a smart contract by address",
+  },
+
+  {
+    args: [],
+    group: "Contracts Registry",
+    async handler(_args, opts, config) {
+      const client = getClient(config);
+      const result = await client.GET("/contracts-registry/templates", {
+        params: {
+          query: q({
+            contractAddress: templatesContractAddress(opts),
+            "page[after]": opts["pageAfter"]
+              ? Number(opts["pageAfter"])
+              : undefined,
+            "page[size]": opts["pageSize"]
+              ? Number(opts["pageSize"])
+              : undefined,
+          }),
+        },
+      });
+      return unwrap(result);
+    },
+    id: "contracts-registry.templates.list",
+    options: [...PAGINATION_OPTIONS, TEMPLATES_ADDRESS_OPTION],
+    segments: ["contracts-registry", "templates", "list"],
+    summary: "List contract templates",
+  },
+
+  {
+    args: [
+      {
+        description: "Template ID",
+        example: "0x1234...",
+        name: "id",
+        required: true,
+      },
+    ],
+    group: "Contracts Registry",
+    async handler(args, opts, config) {
+      const client = getClient(config);
+      const result = await client.GET("/contracts-registry/templates/{id}", {
+        params: {
+          path: { id: requiredArg(args, "id") },
+          query: q({ contractAddress: templatesContractAddress(opts) }),
+        },
+      });
+      return unwrap(result);
+    },
+    id: "contracts-registry.templates.get",
+    options: [TEMPLATES_ADDRESS_OPTION],
+    segments: ["contracts-registry", "templates", "get"],
+    summary: "Get a contract template by ID",
+  },
+
+  {
+    args: [],
+    group: "Contracts Registry",
+    async handler(_args, _opts, config) {
+      const client = getClient(config);
+      const result = await client.GET("/contracts-registry/abi");
+      return unwrap(result);
+    },
+    id: "contracts-registry.abi",
+    options: [],
+    segments: ["contracts-registry", "abi"],
+    summary: "Get the ABI of the Contracts Registry smart contract",
+  },
+];

package/src/commands/did-registry.ts

@@ -0,0 +1,126 @@
+import type { CommandDescriptor } from "./registry.ts";
+
+import { getClient, unwrap } from "../api/fetch.ts";
+import { q } from "../api/params.ts";
+import { contractAddressOptionFor } from "../ledger/registries.ts";
+import { requiredArg } from "./shared/args.ts";
+
+const PAGINATION_OPTIONS = [
+  {
+    description: "Cursor for pagination (page[after])",
+    flags: "--page-after <cursor>",
+  },
+  {
+    description: "Maximum number of items per page (page[size])",
+    flags: "--page-size <n>",
+  },
+];
+
+const { option: CONTRACT_ADDRESS_OPTION, resolve: contractAddress } =
+  contractAddressOptionFor("did-registry");
+
+export const didRegistryCommands: CommandDescriptor[] = [
+  {
+    args: [],
+    group: "DID Registry",
+    async handler(_args, opts, config) {
+      const client = getClient(config);
+      const result = await client.GET("/did-registry/identifiers", {
+        params: {
+          query: q({
+            contractAddress: contractAddress(opts),
+            controller: opts["controller"],
+            "page[after]": opts["pageAfter"]
+              ? Number(opts["pageAfter"])
+              : undefined,
+            "page[size]": opts["pageSize"]
+              ? Number(opts["pageSize"])
+              : undefined,
+            "verification-method-id": opts["verificationMethodId"],
+            "verification-relationship": opts["verificationRelationship"] as
+              | "assertionMethod"
+              | "authentication"
+              | "capabilityDelegation"
+              | "capabilityInvocation"
+              | "keyAgreement"
+              | undefined,
+          }),
+        },
+      });
+      return unwrap(result);
+    },
+    id: "did-registry.identifiers.list",
+    options: [
+      ...PAGINATION_OPTIONS,
+      CONTRACT_ADDRESS_OPTION,
+      {
+        description: "Filter by controller DID",
+        flags: "--controller <did>",
+      },
+      {
+        description:
+          "Filter by verification method id (e.g. did:ebsi:z...#key-1)",
+        flags: "--verification-method-id <id>",
+      },
+      {
+        description:
+          "Filter by verification relationship " +
+          "(authentication, assertionMethod, keyAgreement, capabilityInvocation, capabilityDelegation)",
+        flags: "--verification-relationship <rel>",
+      },
+    ],
+    segments: ["did-registry", "identifiers", "list"],
+    summary:
+      "List all EBSI DIDs. Supports pagination and filtering by controller.",
+  },
+
+  {
+    args: [
+      {
+        description: "The DID to resolve (e.g. did:ebsi:ziDnioxYYLW1a3FDD...)",
+        example: "did:ebsi:ziDnioxYYLW1a3FDD",
+        name: "did",
+        required: true,
+      },
+    ],
+    group: "DID Registry",
+    async handler(args, opts, config) {
+      const client = getClient(config);
+      const did = requiredArg(args, "did");
+      const result = await client.GET("/did-registry/identifiers/{did}", {
+        params: {
+          path: { did },
+          query: q({
+            contractAddress: contractAddress(opts),
+            "valid-at": opts["validAt"],
+          }),
+        },
+      });
+      return unwrap(result);
+    },
+    id: "did-registry.identifiers.get",
+    options: [
+      CONTRACT_ADDRESS_OPTION,
+      {
+        description: "Retrieve DID document as of this ISO-8601 date",
+        flags: "--valid-at <date>",
+      },
+    ],
+    segments: ["did-registry", "identifiers", "get"],
+    summary: "Resolve a DID document by DID",
+  },
+
+  {
+    args: [],
+    group: "DID Registry",
+    async handler(_args, _opts, config) {
+      const client = getClient(config);
+      const result = await client.GET("/did-registry/abi");
+      return unwrap(result);
+    },
+    id: "did-registry.abi",
+    options: [],
+    segments: ["did-registry", "abi"],
+    summary: "Get the ABI of the DID Registry smart contract",
+  },
+];

package/src/commands/faucet.ts

@@ -0,0 +1,112 @@
+import { ethers } from "ethers";
+
+import type { CommandDescriptor } from "./registry.ts";
+
+/**
+ * Hardhat's first pre-funded development account, derived from its default
+ * "test test … junk" mnemonic. Published in Hardhat's own documentation and
+ * identical on every local node, so it is a convenience default, never a
+ * secret — which is also why it is only ever useful against a local chain.
+ */
+const HARDHAT_ACCOUNT_2_PRIVATE_KEY =
+  "0x5de4111afa1a4b94908f83103eb1f1706367c2e68ca870fc3fb9a804cdab365a";
+
+/**
+ * Default JSON-RPC endpoint, matching `LOCAL_HARDHAT_NETWORK_URL` in
+ * `contracts/deploy-toolkit/.env.example`.
+ *
+ * Unlike every other command, the faucet talks to the node directly rather
+ * than through the API's `/ledger` proxy: that proxy requires a Bearer token,
+ * and funding an account is usually the step that comes *before* it can
+ * obtain one.
+ */
+const DEFAULT_RPC_URL = "http://127.0.0.1:8545";
+
+const DEFAULT_AMOUNT_IN_ETH = "1";
+
+export const faucetCommands: CommandDescriptor[] = [
+  {
+    args: [
+      {
+        description: "Address to fund (0x-prefixed).",
+        example: "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC",
+        name: "to",
+        required: true,
+      },
+    ],
+    group: "Faucet",
+    async handler(args, opts) {
+      const to = args["to"] ?? "";
+      if (!ethers.isAddress(to)) {
+        throw new Error(
+          `Invalid "to" address: ${to === "" ? "(missing)" : to}. ` +
+            "Expected a 0x-prefixed 20-byte Ethereum address.",
+        );
+      }
+
+      const amountInEth = opts["amountInEth"] ?? DEFAULT_AMOUNT_IN_ETH;
+      let value: bigint;
+      try {
+        value = ethers.parseEther(amountInEth);
+      } catch {
+        throw new Error(
+          `Invalid --amount-in-eth value: ${amountInEth}. Expected a decimal amount of ETH, e.g. "0.5".`,
+        );
+      }
+      if (value <= 0n) {
+        throw new Error(
+          `Invalid --amount-in-eth value: ${amountInEth}. Expected a positive amount.`,
+        );
+      }
+
+      const rpcUrl = opts["rpcUrl"] ?? DEFAULT_RPC_URL;
+      const provider = new ethers.JsonRpcProvider(rpcUrl);
+      const privateKey = opts["privateKey"] ?? HARDHAT_ACCOUNT_2_PRIVATE_KEY;
+      let funder: ethers.Wallet;
+      try {
+        funder = new ethers.Wallet(privateKey, provider);
+      } catch {
+        throw new Error(
+          "Invalid --private-key: expected a 0x-prefixed secp256k1 private key hex.",
+        );
+      }
+
+      const transaction = await funder.sendTransaction({ to, value });
+      const receipt = await transaction.wait();
+
+      return {
+        amountInEth: ethers.formatEther(value),
+        blockNumber: receipt?.blockNumber ?? undefined,
+        from: funder.address,
+        hash: transaction.hash,
+        newBalanceInEth: ethers.formatEther(await provider.getBalance(to)),
+        to,
+      };
+    },
+    id: "faucet",
+    options: [
+      {
+        description:
+          "Private key funding the transfer (0x-prefixed hex). " +
+          "Defaults to Hardhat's pre-funded account #0.",
+        flags: "--private-key <hex>",
+      },
+      {
+        defaultValue: DEFAULT_AMOUNT_IN_ETH,
+        description: 'Amount of ETH to send, e.g. "0.5".',
+        flags: "--amount-in-eth <eth>",
+      },
+      {
+        defaultValue: DEFAULT_RPC_URL,
+        description:
+          "JSON-RPC endpoint of the node to send the transfer to. " +
+          "The faucet bypasses the API's /ledger proxy, so this is a node URL, not an API base URL.",
+        flags: "--rpc-url <url>",
+      },
+    ],
+    segments: ["faucet"],
+    summary:
+      "Fund an address with ETH from a local development chain. " +
+      "Defaults to sending 1 ETH from Hardhat's account #0 via http://127.0.0.1:8545.",
+  },
+];

package/src/commands/health.ts

@@ -0,0 +1,21 @@
+import type { CommandDescriptor } from "./registry.ts";
+
+export const healthCommands: CommandDescriptor[] = [
+  {
+    args: [],
+    group: "Health",
+    async handler(_args, _opts, config) {
+      const response = await fetch(`${config.baseUrl}/health`, {
+        headers: { Accept: "application/json" },
+      });
+      if (!response.ok) {
+        throw new Error(`Health check failed: HTTP ${String(response.status)}`);
+      }
+      return response.json();
+    },
+    id: "health.check",
+    options: [],
+    segments: ["health"],
+    summary: "Check the health of the EBSI API and its blockchain node",
+  },
+];