NextGenSoftware.OASIS.API.Providers.Web3CoreOASIS
2.0.5
See the version list below for details.
dotnet add package NextGenSoftware.OASIS.API.Providers.Web3CoreOASIS --version 2.0.5
NuGet\Install-Package NextGenSoftware.OASIS.API.Providers.Web3CoreOASIS -Version 2.0.5
<PackageReference Include="NextGenSoftware.OASIS.API.Providers.Web3CoreOASIS" Version="2.0.5" />
<PackageVersion Include="NextGenSoftware.OASIS.API.Providers.Web3CoreOASIS" Version="2.0.5" />
<PackageReference Include="NextGenSoftware.OASIS.API.Providers.Web3CoreOASIS" />
paket add NextGenSoftware.OASIS.API.Providers.Web3CoreOASIS --version 2.0.5
#r "nuget: NextGenSoftware.OASIS.API.Providers.Web3CoreOASIS, 2.0.5"
#:package NextGenSoftware.OASIS.API.Providers.Web3CoreOASIS@2.0.5
#addin nuget:?package=NextGenSoftware.OASIS.API.Providers.Web3CoreOASIS&version=2.0.5
#tool nuget:?package=NextGenSoftware.OASIS.API.Providers.Web3CoreOASIS&version=2.0.5
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- Uniquebytes32based 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:
Install Hardhat and Dependencies:
npm install --save-dev hardhat @nomicfoundation/hardhat-toolbox ethersHardhat Configuration:
Create or update the
hardhat.config.cjsfile 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], }, }, };Environment Variables:
Store your private key in a
.envfile:PRIVATE_KEY=your_private_keyLoad environment variables in your
hardhat.config.cjsfile: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:
Generate a New Ethereum Address:
Use MetaMask or any other Ethereum wallet to generate a new address.
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.
Store Your Private Key:
Save your private key in a
.envfile as shown above.
Faucets for Test Networks
To get test ETH or tokens on the test networks, use the following faucets:
Polygon Mumbai Faucet: faucet.polygon.technology
Rootstock Faucet: faucet.rootstock.io
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:
Sign Up on Etherscan:
- Visit Etherscan and sign up for a free account if you don't already have one.
Login to Your Account:
- After signing up, log in to your Etherscan account.
Access API Keys:
- Once logged in, navigate to the API Keys section from your account dashboard.
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".
Copy Your API Key:
- After the key is generated, copy it for use in your Hardhat configuration.
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
.envfile:
ETHERSCAN_API_KEY=your_etherscan_api_key- Save the API key in a secure place. It’s recommended to store it in an environment variable in your
Use Your API Key in Hardhat:
- Update your
hardhat.config.cjsfile 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, }, };- Update your
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, andrevertfor 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:
Install Solhint:
npm install -D solhintCreate a Solhint Configuration File:
Create a
.solhint.jsonfile 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 }] } }Lint Your Solidity Code:
Run
solhinton 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 | Versions 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. |
-
net10.0
- Nethereum.HdWallet (>= 7.0.0)
- Nethereum.RPC (>= 7.0.0)
- Nethereum.Signer (>= 7.0.0)
- Nethereum.Web3 (>= 7.0.0)
- NextGenSoftware.OASIS.API.Core (>= 2.0.6)
- NextGenSoftware.OASIS.Common (>= 2.0.5)
- NextGenSoftware.OASIS.Providers.Shared.KeyValueStorage (>= 2.0.1)
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.PolygonOASIS
Connects the OASIS to Polygon -- Ethereum's leading L2 scaling solution offering EVM compatibility, dramatically lower fees, and near-instant finality. Stores OASIS holons, avatars, and NFTs on Polygon PoS or zkEVM with full Ethereum interoperability. Part of the OASIS HOT-Swappable Provider Architecture -- 55+ networks. Ecosystem: https://oasisomniverse.one |
GitHub repositories
This package is not used by any popular GitHub repositories.
NextGenSoftware.OASIS.API.Providers.Web3CoreOASIS v2.0.5
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.4
- Add and verify Web3Core presence and payload checked upserts (80cf90e)
- Add bounded Web3Core record enumeration and native page checks (c0b7d5a)
- Add checked encrypted record history to V2 EVM providers (aa48e66)
- Add explicit Fantom canonical-at-read CQL and verified local demo (16018cf)
- Add explicit Sei block-hash codec and verified native CQL walkthrough (05f436b)
- Add native Arbitrum public balance CQL with fixed official RPC path (dd827e4)
- Add native TON TVM contract proof and fix unsupported CQL capability reporting (0ea8699)
- Apply Web3Core paired avatar lifecycle atomically with payload checks (5565889)
- Bind Ethereum storage preparation to durable usage outbox (a69e95e)
- Bind explicit EVM preparation scopes to usage persistence before submission (a3d1efd)
- Correct Web3Core native nearby coordinate units and errors (5b57ba8)
- Document reusable durable preparation integration and correct provider completion claim (135e315)
- Enable verified public Arbitrum and Polygon wallet balances (f0ef621)
- Encrypt Web3Core canonical records with authenticated identity (c6d6c92)
- Expose existing prepared provider implementations through shared Core capability (257b8dc)
- feat(evm): share exact id-bound escrow and preserve custody ownership (11c3572)
- feat(web3core): send exact native coin through value-bound signed observer (23a2aa5)
- Fix Web3Core avatar detail contract routing and record EVM gaps (cbab849)
- fix(evm): cancel owned status HTTP requests per operation (87426f6)
- fix(evm): capture search scope before collection awaits (bbd1ae8)
- fix(evm): preserve exact private history JSON object values (8508fdc)
- fix(evm): require shared exact ERC721 transfer receipt proof (4de4d55)
- fix(evm): resolve export identities independently of holon versions (692efff)
- fix(evm): share authorized default mint wallet selection across providers (7b3756f)
- fix(evm): share bounded exact wallet history without silent block skipping (6cc8f18)
- fix(evm): share validated native balance reads and activation (5614b11)
- fix(evm): verify native NFT mint evidence and expose token identity (9a1e5c3)
- fix(web3): bind mint metadata and collection to admitted intent (b7e3af3)
- fix(web3): enforce exact ERC721 transfer quantities in API and contract (e68ccad)
- fix(web3): freeze NFT request intent before async admission (91e914b)
- fix(web3): honor explicit ERC721 collection targets and share nonce gate (4fe55ca)
- fix(web3): honor NFT owner signing keys without bypassing preparation (05ef7ba)
- fix(web3): preserve captured roles and guard acknowledged caller publication (aab8f2a)
- fix(web3): preserve signed preparation and native identity for NFT burns (ac79397)
- fix(web3): preserve uint256 NFT token IDs and reject fractional transfers (5a75877)
- fix(web3): reject stale callers and colliding graph keys before dispatch (cd83cfe)
- fix(web3): report returned-root counts across shared reads (02db336)
- fix(web3): retain NFT collection title and loaded status (7b0fbca)
- fix(web3): verify NFT recipient ownership and retain failed postcondition evidence (cadb19e)
- fix(web3core): burn requested exact amount through shared signed engine (e1f4319)
- fix(web3core): implement Polygon and Arbitrum credential selectors (617a551)
- fix(web3core): mint explicit exact tokens through signed native observer (1eb6baa)
- fix(web3core): verify exact signed ERC20 transfers including self sends (069c528)
- Gate EVM broadcast through shared closed preparation owners (53d0d1a)
- Guard Web3Core holon deletion by full identity and payload hash (179d3c1)
- Honor Web3Core single-holon graph read options (6161c3b)
- Implement bounded owned-holon CQL in shared Web3Core V2 provider (6b79516)
- Implement explicit Filecoin native identity and CQL balance source (0c7df54)
- Import and export Web3Core holons through authenticated native storage (4d69c74)
- Include Web3Core private storage implementation and tests (2dd77f0)
Full changelog
https://github.com/NextGenSoftwareUK/OASIS/commits/master/Providers/Blockchain/NextGenSoftware.OASIS.API.Providers.Web3CoreOASIS