NextGenSoftware.OASIS.API.Providers.Web3CoreOASIS 2.0.6

dotnet add package NextGenSoftware.OASIS.API.Providers.Web3CoreOASIS --version 2.0.6
                    
NuGet\Install-Package NextGenSoftware.OASIS.API.Providers.Web3CoreOASIS -Version 2.0.6
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="NextGenSoftware.OASIS.API.Providers.Web3CoreOASIS" Version="2.0.6" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="NextGenSoftware.OASIS.API.Providers.Web3CoreOASIS" Version="2.0.6" />
                    
Directory.Packages.props
<PackageReference Include="NextGenSoftware.OASIS.API.Providers.Web3CoreOASIS" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add NextGenSoftware.OASIS.API.Providers.Web3CoreOASIS --version 2.0.6
                    
#r "nuget: NextGenSoftware.OASIS.API.Providers.Web3CoreOASIS, 2.0.6"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package NextGenSoftware.OASIS.API.Providers.Web3CoreOASIS@2.0.6
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=NextGenSoftware.OASIS.API.Providers.Web3CoreOASIS&version=2.0.6
                    
Install as a Cake Addin
#tool nuget:?package=NextGenSoftware.OASIS.API.Providers.Web3CoreOASIS&version=2.0.6
                    
Install as a Cake Tool

Web3 Core OASIS

OASIS Provider Web3CoreOASIS is created to provide Avatar and Holon entities management, such as Save, Load, and Delete operations by using EVM-compatible blockchains.

Currently, OASIS supports the following EVM-compatible blockchains:

  • EthereumOASIS.
  • ArbitrumOASIS.
  • PolygonOASIS.
  • RootstockOASIS.

EthereumOASIS and ArbitrumOASIS are developed independently, with their own smart contracts and code base. PolygonOASIS and RootstockOASIS are based on Web3CoreOASIS, using its code base, new, efficient, and modern Web3CoreOASIS smart contract.

This approach helps develop a single code base that can be shared and used by multiple providers, making the development process faster.

NFT mint metadata and collection targets

The shared mint adapter uses the maintained OASIS mint(address,string) extension; ERC-721 does not define a universal mint function. An explicit CollectionPublicKey selects that compatible collection, otherwise the configured contract is used. Empty, invalid or zero collections/recipients fail before native RPC. An omitted recipient uses the configured signing wallet. The contract must authorize that signer (the maintained extension is owner-only).

One source-linked EvmNftMintMetadata serializer is shared with standalone Ethereum. It publishes only a JSON envelope with JSONMetaDataURL and JSONMetaData; inline JSON is included only when StoreNFTMetaDataOnChain is explicitly true. False or omitted flags leave it null. The URI remains public. The administrative mint request, avatar/email identifiers and routing/signing controls are not serialized as NFT metadata. NFTManager remains responsible for preparing metadata/URIs and batch minting. Intent is captured before nonce/signing awaits, and the verified native mint event supplies the token ID.

Explicit collection calls reuse the same SDK client, signer, mutation gate and submission/receipt owner. A target differing from an active native preparation owner is rejected before nonce lookup/signing/persistence; it does not bypass admission with another client or signer. Configured-target preparation continues to bind the signed target/calldata. The original two-argument SDK MintAsync overload remains available.

Polygon and ArbitrumOASIS_Web3Core inherit this path; the separate legacy Arbitrum implementation does not. Controlled official-SDK signatures and receipt decoding are not live-chain deployment, contract authorization, finality, fees or full HyperDrive V2 certification. Current evidence and remaining native recovery gates are recorded in Docs/WIP/HyperDrive-Providers/EVM_RECORD_HISTORY_GAPS.md.

Web3CoreOASIS Smart Contract

Web3CoreOASIS Smart Contract comes with a single data entity, interface, and implementation.

Data Entity

Data entity is an object that stores Avatar or Holon data efficiently.

struct EntityOASIS {
    uint256 EntityId;
    bytes32 ExternalId;
    bytes Info;
}
  • EntityId - Unique integer-based identification value.
  • ExternalId - Unique bytes32 based identification (GUID, can be represented as string) value of Avatar or Holon.
  • Info - JSON string containing Avatar and Holon data.

Web3CoreOASIS

Web3CoreOASIS class is a Web3 client, used to call smart contract functions by making RPC calls to the chain.

Web3CoreOASISBaseProvider

Web3CoreOASISBaseProvider class provides an implementation for IOASISStorageProvider interface, by using Web3CoreOASIS.

Hardhat Usage

Configuration

The Hardhat configuration is set up in hardhat.config.cjs, supporting local development, Rootstock, and Polygon networks. The configuration includes compiler settings, network endpoints, and necessary plugins.

To configure Hardhat and include support for the Polygon and Rootstock networks, follow these steps:

  1. Install Hardhat and Dependencies:

    npm install --save-dev hardhat @nomicfoundation/hardhat-toolbox ethers
    
  2. Hardhat Configuration:

    Create or update the hardhat.config.cjs file with the following content:

    require("@nomicfoundation/hardhat-toolbox");
    
    module.exports = {
        solidity: "0.8.4",
        networks: {
            localhost: {
                url: "http://127.0.0.1:8545",
            },
            polygon: {
                url: "https://polygon-rpc.com/",
                accounts: [process.env.PRIVATE_KEY],
            },
            mumbai: {
                url: "https://rpc-mumbai.maticvigil.com",
                accounts: [process.env.PRIVATE_KEY],
            },
            rootstock: {
                url: "https://public-node.testnet.rsk.co",
                accounts: [process.env.PRIVATE_KEY],
            },
        },
    };
    
  3. Environment Variables:

    Store your private key in a .env file:

    PRIVATE_KEY=your_private_key
    

    Load environment variables in your hardhat.config.cjs file:

    require("@nomicfoundation/hardhat-toolbox");
    require("dotenv").config();
    
    module.exports = {
        solidity: "0.8.4",
        networks: {
            localhost: {
                url: "http://127.0.0.1:8545",
            },
            polygon: {
                url: "https://polygon-rpc.com/",
                accounts: [process.env.PRIVATE_KEY],
            },
            mumbai: {
                url: "https://rpc-mumbai.maticvigil.com",
                accounts: [process.env.PRIVATE_KEY],
            },
            rootstock: {
                url: "https://public-node.testnet.rsk.co",
                accounts: [process.env.PRIVATE_KEY],
            },
        },
    };
    
Setting Up Private Keys and Addresses

To interact with the blockchain, you need a private key and an address. Here’s how you can get them:

  1. Generate a New Ethereum Address:

    Use MetaMask or any other Ethereum wallet to generate a new address.

  2. Get Your Private Key:

    Export your private key from MetaMask:

    • Open MetaMask and click on the account icon.
    • Select "Account Details" and then "Export Private Key".
    • Enter your password to reveal the private key.
  3. Store Your Private Key:

    Save your private key in a .env file as shown above.

Faucets for Test Networks

To get test ETH or tokens on the test networks, use the following faucets:

Additional Resources
  • For a guide on porting Ethereum dApps to Rootstock, refer to this tutorial.

Obtaining Etherscan API Key

To interact with Etherscan for verifying and publishing your smart contracts, you need to obtain an API key from Etherscan. Follow these steps to get your Etherscan API key:

  1. Sign Up on Etherscan:

    • Visit Etherscan and sign up for a free account if you don't already have one.
  2. Login to Your Account:

    • After signing up, log in to your Etherscan account.
  3. Access API Keys:

    • Once logged in, navigate to the API Keys section from your account dashboard.
  4. Create a New API Key:

    • Click on "Add" to create a new API key.
    • Provide a name for your API key (e.g., "Web3CoreOASIS") and click "Create New API Key Token".
  5. Copy Your API Key:

    • After the key is generated, copy it for use in your Hardhat configuration.
  6. Store Your API Key Securely:

    • Save the API key in a secure place. It’s recommended to store it in an environment variable in your .env file:
    ETHERSCAN_API_KEY=your_etherscan_api_key
    
  7. Use Your API Key in Hardhat:

    • Update your hardhat.config.cjs file to include the Etherscan API key for contract verification:
    require("@nomicfoundation/hardhat-toolbox");
    require("dotenv").config();
    
    module.exports = {
        solidity: "0.8.4",
        networks: {
            localhost: {
                url: "http://127.0.0.1:8545",
            },
            polygon: {
                url: "https://polygon-rpc.com/",
                accounts: [process.env.PRIVATE_KEY],
            },
            mumbai: {
                url: "https://rpc-mumbai.maticvigil.com",
                accounts: [process.env.PRIVATE_KEY],
            },
            rootstock: {
                url: "https://public-node.testnet.rsk.co",
                accounts: [process.env.PRIVATE_KEY],
            },
        },
        etherscan: {
            apiKey: process.env.ETHERSCAN_API_KEY,
        },
    };
    

Local Network

Start a local Hardhat node with:

npx hardhat node

Deployment Script

Deploy the smart contract using:

npx hardhat run --network localhost scripts/deploy.js

For BNB Smart Chain, set OASIS_BNB_DEPLOY_RPC_URL, OASIS_BNB_DEPLOY_CHAIN_ID and the protected PRIVATE_KEY for the intended deployer. Then run npx hardhat run --network bnb scripts/deploy.js. The command prints the address after the deployment is confirmed and the RPC returns contract bytecode.

Testing

Run unit tests using:

npx hardhat test

Code Style Rules

Code style rules for the project are enforced using solhint, which ensures consistent formatting and best practices for Solidity code. The standard styling rules include:

  • Indentation: Use 4 spaces for indentation.
  • Quotes: Use double quotes for string literals.
  • Line Length: Limit lines to 120 characters.
  • Function Visibility: Explicitly define visibility for all functions.
  • Error Handling: Use require, assert, and revert for error handling.
  • Naming Conventions: Follow camelCase for functions and variables, and PascalCase for contract names.

Using Solhint

solhint is a linter for Solidity code that checks for style violations and potential issues. To use solhint in your project:

  1. Install Solhint:

    npm install -D solhint
    
  2. Create a Solhint Configuration File:

    Create a .solhint.json file in the root of your project with the following content:

    {
        "extends": "solhint:recommended",
        "rules": {
            "indent": ["error", 4],
            "quotes": ["error", "double"],
            "max-line-length": ["error", 120],
            "visibility-modifier-order": ["error"],
            "func-visibility": ["error", { "ignoreConstructors": true }]
        }
    }
    
  3. Lint Your Solidity Code:

    Run solhint on your Solidity files to check for style violations:

    npx solhint "contracts/**/*.sol"
    

These steps ensure your Solidity code adheres to the specified style guidelines, improving readability and maintainability.

Deploy and Test

Deployment

A bash script deploy.sh automates the deployment process. It accepts the network as an argument and optionally runs tests after deployment.

#!/bin/bash
# Usage: ./deploy.sh [network] [run_tests]

NETWORK=$1
RUN_TESTS=$2

if [ -z "$NETWORK" ]; then
  echo "Usage: ./deploy.sh [network] [run_tests]"
  exit 1
fi

if [ "$NETWORK" == "development" ]; then
  npx hardhat node &
  HARDHAT_PID=$!
  sleep 5
fi

npx hardhat run --network $NETWORK scripts/deploy.js

if [ "$RUN_TESTS" == "true" ]; then
  npx hardhat test --network $NETWORK
fi

if [ "$NETWORK" == "development" ]; then
  kill $HARDHAT_PID
fi

Unit Tests

Unit tests are written using the Hardhat framework and Chai assertion library. They include tests for creating avatars, loading avatars, and ensuring data integrity.

const { expect } = require("chai");
const { ethers } = require("hardhat");

describe("Web3CoreOASIS", function () {
    let contract;
    let owner;

    before(async () => {
        const Web3CoreOASIS = await ethers.getContractFactory("Web3CoreOASIS");
        [owner] = await ethers.getSigners();
        contract = await Web3CoreOASIS.deploy();
        await contract.deployed();
    });

    it("should create an avatar", async function () {
        const avatarId = ethers.utils.formatBytes32String("Avatar1");
        const info = ethers.utils.formatBytes32String("Info1");

        await contract.createAvatar(1, avatarId, info);
        const avatar = await contract.getAvatarById(1);

        expect(avatar.ExternalId).to.equal(avatarId);
    });

    it("should load an avatar", async function () {
        const avatar = await contract.getAvatarById(1);
        expect(avatar.ExternalId).to.equal(
            ethers.utils.formatBytes32String("Avatar1")
        );
    });

    it("should update an avatar", async function () {
        const newInfo = ethers.utils.formatBytes32String("NewInfo");
        await contract.updateAvatar(1, newInfo);
        const updatedAvatar = await contract.getAvatarById(1);
        expect(updatedAvatar.Info).to.equal(newInfo);
    });
});

Performance Tests

Performance tests measure the execution time and gas usage of contract functions.

describe("Performance Tests", function () {
    let contract;
    let owner;

    before(async () => {
        const Web3CoreOASIS = await ethers.getContractFactory("Web3CoreOASIS");
        [owner] = await ethers.getSigners();
        contract = await Web3CoreOASIS.deploy();
        await contract.deployed();
    });

    it("should measure performance of createAvatar", async function () {
        const avatarId = ethers.utils.formatBytes32String("Avatar1");
        const info = ethers.utils.formatBytes32String("Info1");

        const startTime = process.hrtime();
        await contract.createAvatar(1, avatarId, info);
        const endTime = process.hrtime(startTime);

        console.log(
            `Execution time for createAvatar: ${endTime[0]}s ${
                endTime[1] / 1000000
            }ms`
        );
    });
});

Gas Estimate Tests

Gas estimate tests ensure that contract functions are optimized for gas usage.

describe("Gas Estimate Tests", function () {
    let contract;
    let owner;

    before(async () => {
        const Web3CoreOASIS = await ethers.getContractFactory("Web3CoreOASIS");
        [owner] = await ethers.getSigners();
        contract = await Web3CoreOASIS.deploy();
        await contract.deployed();
    });

    it("should measure gas usage for createAvatar", async function () {
        const avatarId = ethers.utils.formatBytes32String("Avatar1");
        const info = ethers.utils.formatBytes32String("Info1");

        const tx = await contract.createAvatar(1, avatarId, info);
        const receipt = await tx.wait();

        console.log(`Gas used for createAvatar: ${receipt.gasUsed.toString()}`);
    });
});
Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (20)

Showing the top 5 NuGet packages that depend on NextGenSoftware.OASIS.API.Providers.Web3CoreOASIS:

Package Downloads
NextGenSoftware.OASIS.API.Providers.EthereumOASIS

Connects the OASIS to Ethereum -- the world's leading smart contract platform. Stores OASIS holons, avatars, and NFTs on-chain, interacts with EVM-compatible contracts, and participates in the Ethereum DeFi ecosystem. Fully integrated with the OASIS HOT-Swappable Provider Architecture -- switch to or from Ethereum at runtime with zero code changes. Write-Once-Deploy-Everywhere across 55+ providers. REST API: https://api.web4.oasisomniverse.one | Ecosystem: https://oasisomniverse.one

NextGenSoftware.OASIS.API.Providers.TelosOASIS

Connects the OASIS to Telos -- EOSIO-based high-performance blockchain with 10,000+ TPS, sub-0.5-second block times, feeless native transactions, and an EVM layer (tEVM). Stores OASIS holons, avatars, and tokens. Part of the OASIS HOT-Swappable Provider Architecture. Ecosystem: https://oasisomniverse.one

NextGenSoftware.OASIS.API.Providers.BNBChainOASIS

Connects the OASIS to BNB Chain (Binance Smart Chain) -- a high-performance EVM-compatible blockchain with 3-second blocks and minimal transaction fees. Stores OASIS holons, avatars, and BEP-20/BEP-721 tokens. Part of the OASIS HOT-Swappable Provider Architecture. Ecosystem: https://oasisomniverse.one

NextGenSoftware.OASIS.API.Providers.RootstockOASIS

Connects the OASIS to Rootstock (RSK) -- an EVM-compatible smart contract platform merge-mined with Bitcoin, inheriting Bitcoin's hash power while enabling Solidity contracts and DeFi. Stores OASIS holons, avatars, and rBTC-backed tokens. Part of the OASIS HOT-Swappable Provider Architecture. Ecosystem: https://oasisomniverse.one

NextGenSoftware.OASIS.API.Providers.AvalancheOASIS

Connects the OASIS to Avalanche -- high-performance blockchain delivering sub-second finality, EVM compatibility on the C-Chain, and unlimited scalability via custom subnets. Stores OASIS holons, avatars, and tokens. Part of the OASIS HOT-Swappable Provider Architecture. Ecosystem: https://oasisomniverse.one

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
2.0.6 238 11/14/2026
2.0.5 239 11/14/2026
2.0.4 495 10/13/2026
2.0.3 331 9/28/2026
2.0.2 321 9/28/2026
2.0.0 471 7/12/2026

NextGenSoftware.OASIS.API.Providers.Web3CoreOASIS v2.0.6

WEB4 OASIS API Web3Core OASIS Provider is one of the many WEB2/WEB3 providers that plug in and integtate into the OASIS.

What's new since v2.0.5
- Initial validated package contents and metadata for this release line.

Full changelog
https://github.com/NextGenSoftwareUK/OASIS/commits/master/Providers/Blockchain/NextGenSoftware.OASIS.API.Providers.Web3CoreOASIS