@storagehub/api-augment 0.1.0 → 0.2.1

package/package.json

@@ -1,38 +1,53 @@
 {
   "name": "@storagehub/api-augment",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "",
-  "scripts": {
-    "scrape": "pnpm tsx scripts/scrapeMetadata.ts",
-    "fmt": "biome format .",
-    "fmt:fix": "biome format . --write",
-    "tsc": "tsc --noEmit --pretty",
-    "build": "tsc -b --verbose",
-    "generate:all": "pnpm generate:defs && pnpm generate:meta",
-    "generate:defs": "pnpm tsx node_modules/@polkadot/typegen/scripts/polkadot-types-from-defs.mjs --package @storagehub/api-augment/interfaces  --input ./src/interfaces --endpoint ./storagehub.json",
-    "generate:meta": "pnpm tsx node_modules/@polkadot/typegen/scripts/polkadot-types-from-chain.mjs --package @storagehub/api-augment/interfaces --endpoint ./storagehub.json --output ./src/interfaces"
-  },
   "keywords": [],
   "author": "",
-  "module": "./dist/index.js",
-  "types": "./dist/types/index.d.ts",
+  "module": "./dist/parachain/index.js",
+  "type": "module",
+  "types": "./dist/types/parachain/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/types/index.d.ts",
-      "module": "./dist/index.js",
-      "default": "./dist/index.js"
+      "types": "./dist/types/parachain/index.d.ts",
+      "module": "./dist/parachain/index.js",
+      "default": "./dist/parachain/index.js"
+    },
+    "./parachain": {
+      "types": "./dist/types/parachain/index.d.ts",
+      "module": "./dist/parachain/index.js",
+      "default": "./dist/parachain/index.js"
+    },
+    "./solochain-evm": {
+      "types": "./dist/types/solochain-evm/index.d.ts",
+      "module": "./dist/solochain-evm/index.js",
+      "default": "./dist/solochain-evm/index.js"
     }
   },
   "license": "ISC",
   "dependencies": {
-    "@polkadot/api": "12.4.2",
-    "@polkadot/api-base": "12.4.2",
-    "@polkadot/rpc-core": "12.4.2",
-    "@polkadot/typegen": "12.4.2",
-    "@polkadot/types": "12.4.2",
-    "@polkadot/types-codec": "12.4.2",
-    "@storagehub/types-bundle": "workspace:*",
-    "tsx": "4.19.0",
-    "typescript": "5.5.4"
+    "@polkadot/api": "^16.4.7",
+    "@polkadot/api-base": "^16.4.7",
+    "@polkadot/rpc-core": "^16.4.7",
+    "@polkadot/typegen": "^16.4.7",
+    "@polkadot/types": "^16.4.7",
+    "@polkadot/types-codec": "^16.4.7",
+    "tsx": "4.20.5",
+    "typescript": "^5.9.2",
+    "@storagehub/types-bundle": "0.2.1"
+  },
+  "scripts": {
+    "scrape": "pnpm tsx scripts/scrapeMetadata.ts",
+    "fmt": "biome format .",
+    "fmt:fix": "biome format . --write",
+    "tsc": "tsc --noEmit --pretty",
+    "build": "tsc -p tsconfig.parachain.json && tsc -p tsconfig.solochain-evm.json",
+    "generate:all": "pnpm generate:defs && pnpm generate:meta",
+    "generate:defs": "pnpm generate:defs:parachain && pnpm generate:defs:solochain-evm",
+    "generate:meta": "pnpm generate:meta:parachain && pnpm generate:meta:solochain-evm",
+    "generate:defs:parachain": "pnpm tsx node_modules/@polkadot/typegen/scripts/polkadot-types-from-defs.mjs --package @storagehub/api-augment/parachain/interfaces  --input ./src/parachain/interfaces --endpoint ./metadata-sh-parachain.json",
+    "generate:meta:parachain": "pnpm tsx node_modules/@polkadot/typegen/scripts/polkadot-types-from-chain.mjs --package @storagehub/api-augment/parachain/interfaces --endpoint ./metadata-sh-parachain.json --output ./src/parachain/interfaces",
+    "generate:defs:solochain-evm": "pnpm tsx node_modules/@polkadot/typegen/scripts/polkadot-types-from-defs.mjs --package @storagehub/api-augment/solochain-evm/interfaces  --input ./src/solochain-evm/interfaces --endpoint ./metadata-sh-solochain-evm.json",
+    "generate:meta:solochain-evm": "pnpm tsx node_modules/@polkadot/typegen/scripts/polkadot-types-from-chain.mjs --package @storagehub/api-augment/solochain-evm/interfaces --endpoint ./metadata-sh-solochain-evm.json --output ./src/solochain-evm/interfaces"
   }
-}
+}

package/scripts/scrapeMetadata.ts

@@ -1,5 +1,5 @@
-import fs from "node:fs";
 import { execSync, spawn } from "node:child_process";
+import fs from "node:fs";
 import path from "node:path";
 
 const fetchMetadata = async () => {
@@ -37,41 +37,53 @@ const fetchMetadata = async () => {
   throw new Error("Error fetching metadata");
 };
 
+const runCombination = async (metadataPath: string, dockerComposePath: string) => {
+  console.log(`\n=== Starting container for compose: ${dockerComposePath} ===`);
+  try {
+    // Start services in background
+    spawn(
+      "docker",
+      ["compose", "-f", dockerComposePath, "up", "-d", "--remove-orphans", "--renew-anon-volumes"],
+      { stdio: "inherit" }
+    );
+
+    const metadata = await fetchMetadata();
+    const jsonResponse = await new Response(metadata).json();
+    fs.writeFileSync(metadataPath, JSON.stringify(jsonResponse, null, 2));
+    console.log("✅ Metadata file written to:", metadataPath);
+  } finally {
+    try {
+      execSync(`docker compose -f=${dockerComposePath} down --remove-orphans --volumes`, {
+        stdio: "inherit"
+      });
+    } catch (e) {
+      console.warn("⚠️ Error bringing docker compose down:", e);
+    }
+  }
+};
+
 async function main() {
   const nodePath = path.join(process.cwd(), "..", "target", "release", "storage-hub-node");
-  const metadataPath = path.join(process.cwd(), "storagehub.json");
+  const metadataPaths = [
+    path.join(process.cwd(), "metadata-sh-parachain.json"),
+    path.join(process.cwd(), "metadata-sh-solochain-evm.json")
+  ];
+  const dockerComposePaths = [
+    path.join(process.cwd(), "..", "docker", "local-parachain-compose.yml"),
+    path.join(process.cwd(), "..", "docker", "local-solochain-evm-compose.yml")
+  ];
 
   if (!fs.existsSync(nodePath)) {
     console.error("Storage Hub Node not found at path: ", nodePath);
     throw new Error("File not found");
   }
 
-  // TODO: replace with dockerode
-  spawn(
-    "docker",
-    [
-      "compose",
-      "-f=../docker/local-node-compose.yml",
-      "up",
-      "--remove-orphans",
-      "--renew-anon-volumes"
-    ],
-    {
-      stdio: "inherit"
-    }
-  );
-
-  const metadata = await fetchMetadata();
-  fs.writeFileSync(metadataPath, Buffer.from(metadata));
-
-  console.log("✅ Metadata file written to:", metadataPath);
+  // Run sequentially for each combination
+  for (let index = 0; index < metadataPaths.length; index++) {
+    const metadataPath = metadataPaths[index];
+    const dockerComposePath = dockerComposePaths[index];
+    await runCombination(metadataPath, dockerComposePath);
+  }
 }
 
-main()
-  .catch((error) => {
-    console.error(error);
-    process.exitCode = 1;
-  })
-  .finally(() => {
-    execSync("docker compose -f=../docker/local-node-compose.yml down --remove-orphans --volumes");
-  });
+await main();

package/src/parachain/index.ts

@@ -0,0 +1,3 @@
+import "./interfaces/types-lookup.js";
+import "./interfaces/augment-api.js";
+import "./interfaces/augment-types.js";

package/src/{interfaces → parachain/interfaces}/augment-api-consts.ts

@@ -70,28 +70,53 @@ declare module "@polkadot/api-base/types/consts" {
     };
     fileSystem: {
       /**
-       * Maximum batch of storage requests that can be confirmed at once when calling `bsp_confirm_storing`.
+       * Base deposit held from the User when creating a new storage request. The actual deposit held is this amount
+       * plus the amount required to pay for all BSP's `bsp_volunteer` extrinsic.
        **/
-      maxBatchConfirmStorageRequests: u32 & AugmentedConst<ApiType>;
+      baseStorageRequestCreationDeposit: u128 & AugmentedConst<ApiType>;
+      /**
+       * Basic security replication target for a new storage request.
+       *
+       * This should be high enough so that it gives users a ~1% chance of their file
+       * being controlled by a single malicious entity under certain network conditions.
+       *
+       * For more details, see [crate::types::ReplicationTarget].
+       **/
+      basicReplicationTarget: u32 & AugmentedConst<ApiType>;
       /**
-       * Maximum batch of storage requests that can be responded to at once when calling `msp_respond_storage_requests_multiple_buckets`.
+       * Penalty paid by a BSP when they forcefully stop storing a file.
        **/
-      maxBatchMspRespondStorageRequests: u32 & AugmentedConst<ApiType>;
+      bspStopStoringFilePenalty: u128 & AugmentedConst<ApiType>;
       /**
-       * Maximum number of SPs (MSP + BSPs) that can store a file.
+       * The deposit paid by a user to create a new file deletion request.
        *
-       * This is used to limit the number of BSPs storing a file and claiming rewards for it.
-       * If this number is too high, then the reward for storing a file might be to diluted and pointless to store.
+       * This deposit gets returned to the user when the MSP submits an inclusion proof of the file to
+       * confirm its deletion, but gets sent to the MSP if the MSP did not actually had the file and
+       * sends a non-inclusion proof instead. This is done to prevent users being able to spam MSPs
+       * with malicious file deletion requests.
        **/
-      maxBspsPerStorageRequest: u32 & AugmentedConst<ApiType>;
+      fileDeletionRequestDeposit: u128 & AugmentedConst<ApiType>;
+      /**
+       * High security replication target for a new storage request.
+       *
+       * This should be high enough so that it gives users a ~0.01% chance of their file
+       * being controlled by a single malicious entity under certain network conditions.
+       *
+       * For more details, see [crate::types::ReplicationTarget].
+       **/
+      highSecurityReplicationTarget: u32 & AugmentedConst<ApiType>;
+      /**
+       * Maximum batch of storage requests that can be confirmed at once when calling `bsp_confirm_storing`.
+       **/
+      maxBatchConfirmStorageRequests: u32 & AugmentedConst<ApiType>;
       /**
        * Maximum number of multiaddresses for a storage request.
        **/
       maxDataServerMultiAddresses: u32 & AugmentedConst<ApiType>;
       /**
-       * Maximum number of expired items (per type) to clean up in a single block.
+       * Maximum number of expired items (per type) to clean up in a single tick.
        **/
-      maxExpiredItemsInBlock: u32 & AugmentedConst<ApiType>;
+      maxExpiredItemsInTick: u32 & AugmentedConst<ApiType>;
       /**
        * Maximum byte size of a file path.
        **/
@@ -104,6 +129,10 @@ declare module "@polkadot/api-base/types/consts" {
        * Maximum byte size of a peer id.
        **/
       maxPeerIdSize: u32 & AugmentedConst<ApiType>;
+      /**
+       * Maximum replication target that a user can select for a new storage request.
+       **/
+      maxReplicationTarget: u32 & AugmentedConst<ApiType>;
       /**
        * Maximum number of file deletion requests a user can have pending.
        **/
@@ -113,7 +142,7 @@ declare module "@polkadot/api-base/types/consts" {
        **/
       maxUserPendingMoveBucketRequests: u32 & AugmentedConst<ApiType>;
       /**
-       * Number of blocks required to pass between a BSP requesting to stop storing a file and it being able to confirm to stop storing it.
+       * Number of ticks required to pass between a BSP requesting to stop storing a file and it being able to confirm to stop storing it.
        **/
       minWaitForStopStoring: u32 & AugmentedConst<ApiType>;
       /**
@@ -121,13 +150,60 @@ declare module "@polkadot/api-base/types/consts" {
        **/
       moveBucketRequestTtl: u32 & AugmentedConst<ApiType>;
       /**
-       * Time-to-live for a pending file deletion request, after which a priority challenge is sent out to enforce the deletion.
+       * Standard security replication target for a new storage request.
+       *
+       * This should be high enough so that it gives users a ~0.1% chance of their file
+       * being controlled by a single malicious entity under certain network conditions.
+       *
+       * For more details, see [crate::types::ReplicationTarget].
        **/
-      pendingFileDeletionRequestTtl: u32 & AugmentedConst<ApiType>;
+      standardReplicationTarget: u32 & AugmentedConst<ApiType>;
       /**
        * Time-to-live for a storage request.
        **/
       storageRequestTtl: u32 & AugmentedConst<ApiType>;
+      /**
+       * Super high security replication target for a new storage request.
+       *
+       * This should be high enough so that it gives users a ~0.001% chance of their file
+       * being controlled by a single malicious entity under certain network conditions.
+       *
+       * For more details, see [crate::types::ReplicationTarget].
+       **/
+      superHighSecurityReplicationTarget: u32 & AugmentedConst<ApiType>;
+      /**
+       * The amount of ticks that have to pass for the threshold to volunteer for a specific storage request
+       * to arrive at its maximum value.
+       **/
+      tickRangeToMaximumThreshold: u32 & AugmentedConst<ApiType>;
+      /**
+       * The treasury account of the runtime, where a fraction of each payment goes.
+       **/
+      treasuryAccount: AccountId32 & AugmentedConst<ApiType>;
+      /**
+       * Ultra high security replication target for a new storage request.
+       *
+       * This should be high enough so that it gives users a ~0.0001% chance of their file
+       * being controlled by a single malicious entity under certain network conditions.
+       *
+       * For more details, see [crate::types::ReplicationTarget].
+       **/
+      ultraHighSecurityReplicationTarget: u32 & AugmentedConst<ApiType>;
+      /**
+       * The amount of ticks that the user has to pay upfront when issuing a storage request.
+       *
+       * This is to compensate the system load that the process of file retrieval will have on the network.
+       * If this did not exist, a malicious user could spam the network with huge files, making BSPs change
+       * their capacity and download a lot of data while the user might not even have the balance to
+       * store and pay those BSPs in the long term.
+       *
+       * It initially exists as a deterrent, since these funds will be transferred to the treasury and not to the BSPs
+       * of the network. Governance can then decide what to do with these funds.
+       *
+       * The amount that the user is going to have to pay is calculated as follows:
+       * `Replication Target Chosen * PricePerGigaUnitPerTick * File Size in Gigabytes * UpfrontTicksToPay`
+       **/
+      upfrontTicksToPay: u32 & AugmentedConst<ApiType>;
       /**
        * Generic const
        **/
@@ -244,14 +320,27 @@ declare module "@polkadot/api-base/types/consts" {
       [key: string]: Codec;
     };
     paymentStreams: {
+      /**
+       * The base deposit for a new payment stream. The actual deposit will be this constant + the deposit calculated using the `NewStreamDeposit` constant.
+       **/
+      baseDeposit: u128 & AugmentedConst<ApiType>;
+      /**
+       * The maximum amount of Users that a Provider can charge in a single extrinsic execution.
+       * This is used to prevent a Provider from charging too many Users in a single block, which could lead to a DoS attack.
+       **/
+      maxUsersToCharge: u32 & AugmentedConst<ApiType>;
       /**
        * The number of ticks that correspond to the deposit that a User has to pay to open a payment stream.
        * This means that, from the balance of the User for which the payment stream is being created, the amount
-       * `NewStreamDeposit * rate` will be held as a deposit.
-       * In the case of dynamic-rate payment streams, `rate` will be `amount_provided * current_service_price`, where `current_service_price` has
-       * to be provided by the pallet using the `PaymentStreamsInterface` interface.
+       * `NewStreamDeposit * rate + BaseDeposit` will be held as a deposit.
+       * In the case of dynamic-rate payment streams, `rate` will be `amount_provided_in_giga_units * price_per_giga_unit_per_tick`, where `price_per_giga_unit_per_tick` is
+       * obtained from the `CurrentPricePerGigaUnitPerTick` storage.
        **/
       newStreamDeposit: u32 & AugmentedConst<ApiType>;
+      /**
+       * The treasury account of the runtime, where a fraction of each payment goes.
+       **/
+      treasuryAccount: AccountId32 & AugmentedConst<ApiType>;
       /**
        * The number of ticks that a user will have to wait after it has been flagged as without funds to be able to clear that flag
        * and be able to pay for services again. If there's any outstanding debt when the flag is cleared, it will be paid.
@@ -327,6 +416,17 @@ declare module "@polkadot/api-base/types/consts" {
        * The maximum number of custom challenges that can be made in a single checkpoint block.
        **/
       maxCustomChallengesPerBlock: u32 & AugmentedConst<ApiType>;
+      /**
+       * The maximum number of Providers that can be slashed per tick.
+       *
+       * Providers are marked as slashable if they are found in the [`TickToProvidersDeadlines`] StorageMap
+       * for the current challenges tick. It is expected that most of the times, there will be little to
+       * no Providers in the [`TickToProvidersDeadlines`] StorageMap for the current challenges tick. That
+       * is because Providers are expected to submit proofs in time. However, in the extreme scenario where
+       * a large number of Providers are missing the proof submissions, this configuration is used to keep
+       * the execution of the `on_poll` hook bounded.
+       **/
+      maxSlashableProvidersPerTick: u32 & AugmentedConst<ApiType>;
       /**
        * The maximum amount of Providers that can submit a proof in a single block.
        * Although this can be seen as an arbitrary limit, if set to the already existing
@@ -345,11 +445,16 @@ declare module "@polkadot/api-base/types/consts" {
        * If less than this percentage of blocks are not full, the networks is considered to be presumably
        * under a spam attack.
        * This can also be thought of as the maximum ratio of misbehaving collators tolerated. For example,
-       * if this is set to `Perbill::from_percent(50)`, then if more than half of the last `BlockFullnessPeriod`
+       * if this is set to `Perbill::from_percent(50)`, then if more than half of the last [`Config::BlockFullnessPeriod`]
        * blocks are not full, then one of those blocks surely was produced by an honest collator, meaning
-       * that there was at least one truly _not_ full block in the last `BlockFullnessPeriod` blocks.
+       * that there was at least one truly _not_ full block in the last [`Config::BlockFullnessPeriod`] blocks.
        **/
       minNotFullBlocksRatio: Perbill & AugmentedConst<ApiType>;
+      /**
+       * The fee charged for submitting a priority challenge.
+       * This fee goes to the Treasury, and is used to prevent spam.
+       **/
+      priorityChallengesFee: u128 & AugmentedConst<ApiType>;
       /**
        * The number of random challenges that are generated per block, using the random seed
        * generated for that block.
@@ -380,6 +485,14 @@ declare module "@polkadot/api-base/types/consts" {
       [key: string]: Codec;
     };
     providers: {
+      /**
+       * The amount of blocks that a BSP must wait before being able to sign off, after being signed up.
+       *
+       * This is to prevent BSPs from signing up and off too quickly, thus making it harder for an attacker
+       * to suddenly have a large portion of the total number of BSPs. The reason for this, is that the
+       * attacker would have to lock up a large amount of funds for this period of time.
+       **/
+      bspSignUpLockPeriod: u32 & AugmentedConst<ApiType>;
       /**
        * The amount that an account has to deposit to create a bucket.
        **/
@@ -400,10 +513,11 @@ declare module "@polkadot/api-base/types/consts" {
        * The maximum amount of blocks after which a sign up request expires so the randomness cannot be chosen
        **/
       maxBlocksForRandomness: u32 & AugmentedConst<ApiType>;
+      maxCommitmentSize: u32 & AugmentedConst<ApiType>;
       /**
-       * The maximum amount of Buckets that a MSP can have.
+       * Maximum number of expired items (per type) to clean up in a single block.
        **/
-      maxBuckets: u32 & AugmentedConst<ApiType>;
+      maxExpiredItemsInBlock: u32 & AugmentedConst<ApiType>;
       /**
        * The estimated maximum size of an unknown file.
        *
@@ -426,6 +540,14 @@ declare module "@polkadot/api-base/types/consts" {
        * The minimum amount of blocks between capacity changes for a SP
        **/
       minBlocksBetweenCapacityChanges: u32 & AugmentedConst<ApiType>;
+      /**
+       * Time-to-live for a provider to top up their deposit to cover a capacity deficit.
+       *
+       * This TTL is used to determine at what point to insert the expiration item in the
+       * [`ProviderTopUpExpirations`] storage which is processed in the `on_idle` hook at
+       * the time when the tick has been reached.
+       **/
+      providerTopUpTtl: u32 & AugmentedConst<ApiType>;
       /**
        * The slash factor deducted from a Storage Provider's deposit for every single storage proof they fail to provide.
        **/
@@ -449,6 +571,11 @@ declare module "@polkadot/api-base/types/consts" {
        * - The slashed funds are transferred.
        **/
       treasury: AccountId32 & AugmentedConst<ApiType>;
+      /**
+       * 0-size bucket fixed rate payment stream (i.e. the amount charged as a base
+       * fee for a bucket that doesn't have any files yet)
+       **/
+      zeroSizeBucketFixedRate: u128 & AugmentedConst<ApiType>;
       /**
        * Generic const
        **/