NextGenSoftware.OASIS.API.Providers.NEAROASIS 2.0.5

There is a newer version of this package available.
See the version list below for details.
dotnet add package NextGenSoftware.OASIS.API.Providers.NEAROASIS --version 2.0.5
                    
NuGet\Install-Package NextGenSoftware.OASIS.API.Providers.NEAROASIS -Version 2.0.5
                    
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.NEAROASIS" Version="2.0.5" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="NextGenSoftware.OASIS.API.Providers.NEAROASIS" Version="2.0.5" />
                    
Directory.Packages.props
<PackageReference Include="NextGenSoftware.OASIS.API.Providers.NEAROASIS" />
                    
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.NEAROASIS --version 2.0.5
                    
#r "nuget: NextGenSoftware.OASIS.API.Providers.NEAROASIS, 2.0.5"
                    
#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.NEAROASIS@2.0.5
                    
#: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.NEAROASIS&version=2.0.5
                    
Install as a Cake Addin
#tool nuget:?package=NextGenSoftware.OASIS.API.Providers.NEAROASIS&version=2.0.5
                    
Install as a Cake Tool

NextGenSoftware.OASIS.API.Providers.NEAROASIS

NEAR adapter using a pinned official near-api-js SDK through a Node bridge. Native account/key/balance/transfer operations and configured-contract storage/token/NFT/bridge paths have scoped retained-local-chain tests. Those custom-contract fixtures do not certify general NEP-standard interoperability, every provider option, hosted APIs, fee settlement or full HyperDrive V2 policy behavior.

Custom token mint intent

Generic contract calls and native transfers accept an acknowledgement only when its original transaction ID, signer and receiver match the dispatched operation and execution is explicitly FINAL/successful. A bound finalized native failure is a rejection; missing, mismatched, nonfinal or unavailable evidence is marked as requiring reconciliation before replay. The existing outcome classifier is reused. This is not durable pre-broadcast journaling, fee settlement or native certification of every mutation; ordinary record put/delete paths remain separate review gates.

Acknowledgements must contain exactly the admitted action. Transfers bind the yocto amount; calls bind method, deposit, numeric gas and decoded JSON arguments captured before awaiting the SDK. The bridge receives the explicit gas value from this request owner. Equivalent JSON arguments are compared structurally; this is not a claim of signed-byte identity or protection from every cross-language numeric serialization issue.

Contract-call arguments cross the C#/Node boundary as canonical base64 of the captured UTF8 JSON, then enter the official SDK as raw bytes. The decoder validates base64, UTF8 and JSON syntax without reserializing JavaScript numbers. This preserves large integers and high-precision decimals in the outbound argument bytes; contract-side parsing and read-only view argument precision are separate concerns.

The retained local signed-acknowledgement test verifies a one-yocto self-transfer plus fixed public synthetic NFT mint/burn, matching native receipts and independent finalized-status/readback checks. It journals before submission and retains unknown outcomes rather than replaying; successful cleanup requires verified NFT absence. This bounded success proof is not failure/recovery, full-provider or hosted certification. Run only through the explicit reusable -VerifySignedAcknowledgements scope, preserving its original report/journal before any later run.

The same native test now also verifies a deliberate contract rejection: its original receipt ID survives and independent status reports Failed. A shared submission owner preserves native failure outcomes (throwOnFailure:false) and disables the SDK's InvalidNonce re-sign recursion (retries:0) for generic calls, transfers and checked-record actions. This does not disable or certify every provider/RPC transport retry, nor prove forced-response-loss recovery. Failed execution can still consume native gas.

-VerifyCheckedWrites runs the existing encrypted conditional-record native test separately: create/archive replacement, stale/archive-collision rejection, duplicate identity selection, and acknowledged fixture cleanup with independent absence. It reuses the retained key/ledger and preserves old completed journals in the existing history file. Neither isolated native scope is a full-interface or full-suite certification.

Filtered search, metadata and nearby results report LoadedCount for returned matches/roots, not the size of underlying collections. Nearby results are materialized before publication; malformed-coordinate failures clear the result, IsLoaded and count. These logical counts are not native RPC usage, fees or evidence that every other read route is certified.

Minting uses the maintained custom OASIS token_mint contract operation, not a universal NEP-141 mint API. TokenAddress selects an explicitly compatible contract; omission keeps the configured contract. ToWalletAddress selects the recipient balance owner; omission keeps the configured account. Explicit blank values are invalid, never silently substituted. The configured contract-owner signer remains unchanged and must be authorized by the selected contract.

Symbol, target, recipient, exact eight-decimal units and serialized title/description/metadata/tags are captured before activation. Unsupported precision rejects before SDK activation. Caller mutation during that await cannot redirect issuance or change metadata/amount. This dispatch contract is verified by controlled process-IPC tests; it does not prove native issuance/finality/fees. The latest retained native run remains 15/19 passing with four failures requiring reconciliation; see Docs/WIP/HyperDrive-Providers/NEAR_SIGNER_AND_RECEIPT_AUDIT.md for current evidence and open gates.

Process encoding and native verification limits

SDK stdin/stdout/stderr explicitly use strict UTF8, independent of the host console code page. Controlled echo-process tests reproduce the former non-ASCII decoding defect and verify accented text, emoji and Japanese text after the fix; they are not SDK/native-chain tests. The retained native fixture separately checks Unicode NFT metadata through the deployed contract and official SDK. This fixes client transport decoding, not stored-record schema or on-chain state; no record/key migration or re-encoding was performed.

Reuse the configured SDK/runtime and persisted private storage key. The native evidence runner reconnects to the existing retained ledger and checks deployed contract identity; it must not initialize/reset/redeploy a chain per run. Native gas is not a fixed retail/USD price or fee-free guarantee. Durable unknown-outcome recovery, complete fee accounting, hosted authorization, standard-contract interoperability and full interface/V2 certification remain open; see repository release gates for current report scope and hashes.

Installation

dotnet add package NextGenSoftware.OASIS.API.Providers.NEAROASIS

NuGet versions · Source project

Choose a published version compatible with the other OASIS packages in your application. This guide describes current source; older packages may not contain the same functionality.

Frameworks and dependencies

Declared target frameworks: net10.0.

Direct external package references:

  • NextGenSoftware.OASIS.API.Core

Project references and conditional dependency versions are recorded in the source project. NuGet restore resolves packaged dependencies; do not mix arbitrary DLLs from different release graphs.

Integration and configuration

Use this package for the responsibility described above, alongside its owning OASIS runtime/provider integration. Inspect the source project's public APIs and owning component documentation for construction and configuration; this package installation command does not start an API server, authenticate an avatar or provision an external service.

Provider adapters require their respective service configuration and credentials. Runtime libraries require the host application's lifecycle and persistent paths where applicable. Supply only the settings actually required by the owning component; do not copy production DNA into a client or public release.

Errors and security

Avatar, avatar-detail and holon contract storage now requires OASIS_NEAR_STORAGE_ENCRYPTION_KEY: a separately generated, persistently retained Base64-encoded 32-byte key. Configure it through protected host secrets; do not derive it from the account signing key, commit it, print it, or generate a replacement on every startup. Losing it prevents reading existing encrypted records. Back it up securely alongside the deployment's network and contract identity.

The existing shared authenticated-encryption codec protects storage values before SDK dispatch and binds them to network, contract and record key. Views decrypt locally, including collection queries. Plaintext records, incorrect keys and swapped ciphertext fail closed; there is no plaintext fallback or automatic migration. Generic storage get/list/put/delete requires key configuration before starting the SDK process. Token/NFT contract calls and their intentionally public metadata are separate from this record-storage boundary.

The encryption boundary has focused codec/preflight tests and a 2026-10-18 retained local-chain SDK roundtrip:12 native cases passed after the raw yocto balance overflow fix. Raw finalized contract inspection also confirmed encrypted record envelopes. This is scoped evidence, not complete interface/options/version or hosted acceptance. The evidence runner connects only to an explicitly retained environment; it does not initialize/reset a sandbox, deploy contracts, download packages or restore .NET dependencies. Configure OASIS_NEAR_REUSABLE_RPC_URL (loopback HTTP), OASIS_NEAR_REUSABLE_CHAIN_ID, OASIS_NEAR_REUSABLE_CONTRACT_ID and OASIS_NEAR_REUSABLE_SIGNER_PATH (inside /var/tmp/oasis-near-evidence/). Deployed finalized code must match the locally compiled contract byte-for-byte. Provision missing native tools once explicitly and retain them; never use the sandbox SDK's destructive default initialization against an existing ledger.

Owned test credentials pass from the Linux SDK host to Windows through stdin, not a plaintext settings file or command line. The Windows test host creates LocalAppData/OASIS/provider-evidence/near/storage-key.dpapi only if absent, refuses to overwrite/replace it and restores pre-existing process environment after execution. Actual configured execution now verifies that DPAPI success path. The retained sandbox2.6.2 runtime and SDK2.0.0 compiler tools were installed once; contract compilation is verified using Scripts/run_near_provider_evidence.sh --compile-only. That explicit mode never starts a node. bootstrap-retained.mjs --inspect is read-only; --deploy-once explicitly bootstraps the reviewed empty local account with a durable pre-broadcast original hash, refuses prior intents, and verifies FINAL before checking code. --verify-original only reconciles that original, never broadcasts. Preserve the existing ledger, storage key and bootstrap journals. Detailed evidence and remaining gates: Docs/WIP/HyperDrive-Providers/HYPERDRIVE_V2_CURRENT_RELEASE_GATES.md in the parent repository.

Record history and costs

Network configuration is explicit: networkId and chainId must both be nonempty and identify the same RPC chain. The installed official SDK's getNetworkId() returns node-status chain_id; activation checks the matching configuration and then probes that identity. The constructor retains chainId rather than ignoring it. Mainnet remains the default for both fields. For a custom/test chain, set BOTH DNA Network and ChainId (BootLoader already forwards them); changing only Network while leaving the mainnet ChainId default now rejects activation. No hosted DNA variables are changed automatically.

Transaction-status lookup distinguishes execution finality from execution success. The SDK bridge returns the native outcome; its transaction ID must match the requested hash. Only FINAL+SuccessValue maps to Completed; FINAL+Failure maps to Failed, while nonfinal execution remains Pending. Unknown finality or malformed final outcomes return explicit lookup errors, not fabricated successful completion. Always check IsError before reading a status result. These statuses describe the native transaction, not cross-chain settlement or fee recovery.

The retained evidence host requires failed-status-original.json, created by the bounded read-only find-failed-status.mjs helper from an already-existing finalized failed transaction. It never signs, submits, resets or replaces an original. Existing evidence is reconciled read-only; a pruned/unavailable original is a verification failure, not permission to replay it. The host forwards only its public hash to the native test and restores the prior process environment afterward.

Nearby network-interface queries use shared StoredRecordLocationQuery: request coordinates are integer microdegrees, metadata coordinates are invariant-culture degrees, radius is metres. Invalid request ranges/radii/types reject before storage access. Malformed stored coordinate pairs produce an explicit error with no nearby result collection; records with neither coordinate are omitted. Matching occurs after encrypted record reads, without a public location index or provider-specific distance implementation.

Search now validates and evaluates the existing ISearchParams contract with shared StoredRecordSearch, rather than silently reducing requests to text-group unions. Owner/parent scope, metadata matching, group operators, text/number/date selections, type targets and field masks use that common evaluator. Invalid current-avatar scope or negative history/depth rejects before activation. Matching runs locally after authenticated record decryption; this introduces no public email/username/metadata index. Whole-prefix listing and historical/descendant reads still scale with retained records and may incur RPC-service usage; this is not an indexed server-side query or a full hosted authorization/performance certification.

Avatar, avatar-detail and holon record writes use detached canonical snapshots too. Rejected activation or record-storage preflight leaves caller IDs, provider links and version stamps unchanged; successful acknowledged writes publish those fields back to the caller. This does not imply rollback of an already submitted transaction or guarantee recovery of unknown outcomes. The focused failure checks distinguish rejected activation and controlled post-activation missing-encryption-key rejection from live native write acceptance.

Graph saves preflight the entire selected forest using shared HolonGraphWritePlan before activation or signed writes. Null/repeated nodes, cycles, duplicate IDs, conflicting selected-child parents and negative depths fail explicitly. Depth selection follows the OASIS save contract: root counts as depth1; maxChildDepth0 is unlimited. The batch argument is curentChildDepth (the base interface's spelling), not an archival version. The one-argument save overload follows the interface defaults: save children recursively. Snapshots receive planned identities; caller IDs/parents/provider keys/version stamps are published only after acknowledged current-record writes. Failed parents block their selected descendants, while continueOnError permits unrelated branches. A result reports the acknowledged count; a later failure does NOT roll back those writes. Unknown post-submission outcomes still require durable native recovery and are not certified by preflight tests. Named callers that used the previously incorrect version: batch parameter must use curentChildDepth:.

IsVersionControlEnabled defaults to false, matching shared key-value storage. Saves stamp current record versions either way; enabling the property archives the replaced version before each update. Archive records use separate history: keys through the SAME encrypted SDK boundary. An archived update adds one signed contract write (gas/storage) to the current-record write; hard deletion also submits deletes for retained history. These are sequential operations, not an atomic multi-record transaction. A failure can leave an acknowledged archive without the current update, and callers must not assume rollback or safe replay. Production fee admission/recovery, concurrent-writer control, DNA configuration binding and full interface acceptance remain separate open gates; this does not authorize sponsorship.

Version0 selects current data; positive versions select that exact version or return no record, never substitute latest. Shared StoredRecordVersions owns identity validation/version stamps/overflow checks for NEAR and generic key-value storage. Single/list avatar, avatar-detail and holon reads, selectors, search/export and parent queries now forward requested versions. Historical root loads keep descendants at their independent current versions, not a point-in-time graph snapshot. Hard avatar/holon deletion removes that record's history; deleting an avatar is not newly certified as cascading to its separate detail record. Versions overwritten before archiving was enabled cannot be reconstructed. The expanded retained local-chain suite passed13cases on2026-10-18, including historical selectors, root/child version independence and hard-delete paths; it does not prove every option, concurrent failure or hosted API behavior.

For APIs returning OASISResult<T>, check IsError, ErrorCode and Message; do not treat a failed result as success. Preserve useful diagnostics without logging access tokens, passwords or private keys. Keep secrets in the host's appropriate protected configuration or platform storage.

Platform requirements

Target-framework compatibility is not proof that every native dependency or external service works on every operating system. Check the selected version's platform assets and native/service requirements before deployment. Unity/mobile integrations require their supported platform layer and packaging workflow; a managed NuGet archive alone does not establish Android/iOS, IL2CPP or two-device convergence acceptance.

Troubleshooting

Independent custom-token senders (2026-10-18)

Custom-contract token sends now forward the supplied FromWalletAddress and OwnerPrivateKey to the official SDK, like native NEAR sends. Previously the custom branch ignored the owner key and used the service signer, causing contract rejection for independent holders. An explicit independent sender without its key now fails before activation rather than substituting the service key. Default service-owner sends remain supported. Used request fields are frozen before SDK awaits, and exact native/custom units validated before activation.

Current retained native suite17/17 passes153seconds, including an actual funded independent holder returning2custom units after receiving10; balance reads prove issuer92/holder8 and later issuer burn91.75/holder8. Funding and all fees use LOCAL sandbox testNEAR only, not public-chain money. Focused unit39/39 passes1second; legacy default-mainnet template class is excluded, so this is not a complete old unit-project claim. Same SDK7.3.1/runtime2.6.2/ledger/contract retained, node gracefully stopped after verification. Exact hashes and remaining gates are in Docs/WIP/HyperDrive-Providers/HYPERDRIVE_V2_CURRENT_RELEASE_GATES.md.

These custom-token methods target the existing OASIS fixture contract, not generic NEP141 interoperability. General signer authorization, burn/NFT signer coverage, escrow semantics, fee accounting and durable original-transaction recovery remain separate open gates. No API production fee or full-provider certification is implied.

  • Restore/assembly mismatch: pin a coherent set of package versions and inspect the dependency graph.
  • Configuration or authentication error: inspect the owning component's result diagnostics and service requirements without exposing secrets.
  • Native loading failure: verify OS/architecture and required native artifacts rather than suppressing the error.
  • Missing functionality in an older version: compare the immutable released source and release notes, not only the moving Development branch.

Releases and further documentation

[Verified release matrix](https://github.com/NextGenSoftwareUK/OASIS/blob/Development/Docs/WIP/Release and Status/OASIS_RELEASE_STATUS.md) · [Documentation audit](https://github.com/NextGenSoftwareUK/OASIS/blob/Development/Docs/WIP/Release and Status/RELEASE_DOCUMENTATION_AUDIT.md)

Published NuGet versions are immutable. Updated documentation ships with a new unpublished package version after checked promotion and publication. This metadata-backed guide does not replace product-specific API examples or claim unverified platform tests.

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 (1)

Showing the top 1 NuGet packages that depend on NextGenSoftware.OASIS.API.Providers.NEAROASIS:

Package Downloads
NextGenSoftware.OASIS.OASISBootLoader

The OASIS BootLoader provides a single entry point to initialise the entire OASIS ecosystem in any .NET application. Reads OASISDNA configuration, registers and activates all configured providers, sets up Auto-FailOver/LoadBalancing, and returns a ready-to-use OASIS instance. Integrate 55+ decentralised networks into your app with just a few lines of code. Part of the OASIS Omniverse at https://oasisomniverse.one

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
2.0.6 153 11/14/2026
2.0.5 154 11/14/2026
2.0.4 352 10/13/2026
2.0.3 207 9/28/2026
2.0.2 165 9/28/2026
2.0.0 164 7/12/2026

NextGenSoftware.OASIS.API.Providers.NEAROASIS v2.0.5

Connects the OASIS to NEAR Protocol -- a sharded, developer-friendly blockchain with human-readable account names, near-zero fees, and Nightshade sharding for unlimited throughput. Stores OASIS holons, avatars, and tokens. Part of the OASIS HOT-Swappable Provider Architecture. Ecosystem: https://oasisomniverse.one/

What's new since v2.0.4
- Add final-block-pinned NEAR public account CQL source and native tests (d106d18)
- Add native-verified encrypted NEAR conditional SDK writes (224219e)
- Add verified NEAR signed-original SDK preparation primitives (a1b67b8)
- Align NEAR collection version and depth roles with shared storage interface (ab77d0f)
- Bind NEAR NFT bridge deposits to exact successful source lock receipts (0cfa2d6)
- Bind NEAR ordinary storage writes to verified native execution outcomes (76bb983)
- Enable verified NEAR mnemonic signing for token and NFT owners (b23a1a8)
- Enable verified public NEAR wallet balance in Development (74db163)
- Encrypt NEAR record storage using shared authenticated codec (66cc8b4)
- Execute NEAR signed originals through existing preparation owner (16df483)
- feat(near): persist encrypted history with shared version invariants (40f48d6)
- Fence acknowledged NEAR record publication by caller identity (4ee6fa5)
- fix: preserve import acknowledgements and native evidence (273d0f9)
- fix(near): apply shared search filters and group semantics (8dcda80)
- fix(near): bind mutation receipts to admitted native actions (f89b127)
- fix(near): capture search scope before native collection reads (5124fe1)
- fix(near): distinguish failed execution from transaction finality (a25a662)
- fix(near): freeze custom mint target recipient units and metadata (1c7a58d)
- fix(near): honor graph load options using shared projection (e58a7e2)
- fix(near): preflight graph saves before native writes (4571b2d)
- fix(near): preserve caller state when record writes fail (15196a1)
- fix(near): preserve canonical caller edits after acknowledged writes (4594135)
- fix(near): preserve exact JSON argument bytes through real SDK (1549d97)
- fix(near): preserve identity selection diagnostics in export and deletion (3e839bf)
- fix(near): preserve native failure receipts without nonce resigning (fca8426)
- fix(near): preserve Unicode through strict UTF8 SDK process streams (4845ef7)
- fix(near): publish truthful filtered read counts and error state (e424455)
- fix(near): reject conflicting configured chain identity (9fbcc3e)
- fix(near): require bound finalized mutation acknowledgements (e814d13)
- fix(near): resolve captured roles against checked-write observation (90cd410)
- fix(near): scale native amounts safely and verify retained SDK operations (b2115a3)
- fix(near): separate export identity and holon versions (b8cac3d)
- fix(near): validate nearby queries with shared location helper (9233125)
- fix(providers): checkpoint Redis codec and NEAR transfer signers (a321b3a)
- Freeze NEAR NFT mint intent and verify public prepared lifecycles (f8759cf)
- Honor avatar signing wallets for NEAR NFT lock operations (fc5c111)
- Honor independent NEAR token sender signing credentials (9cd46d0)
- Honor NEAR NFT owner signers and retain acknowledged followup receipts (f7c448f)
- Implement exact NEAR token escrow adapter and signer verification (ab25688)
- Integrate verified native NEAR managed storage lifecycle (824a404)
- Keep unavailable NEAR transaction observations pending and bound readonly SDK calls (84b7a9f)
- Limit NEAR SDK worker signing keys and inherited credential exposure (966724d)
- Make NEAR evidence reuse explicit retained environments safely (778f42f)
- Map NEAR NFT custody calls and source proofs to exact native deposit IDs (be911f6)
- MOVING DOCS AROUND (32a8004)
- Organize HyperDrive provider working reports under dedicated WIP folder (b699b48)
- Page NEAR native records at finalized snapshots and verify owner token burns (d44710e)
- Persist exact NEAR deployment originals and verify custody code upgrade (fb6e49b)
- Preserve NEAR checked calldata and acknowledged follow-up identities (06c4583)
- Recover NEAR bounded CQL and propagate owned SDK query cancellation (6086599)

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