Update documentation and metadata for v1.0.1: Add README.nuget.md to fix NuGet README rendering, expand USAGE.md with new examples and Native AOT publishing guidance, refresh main README for stable release, and update version, changelog, and package metadata.

Author: jecacs

CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to SolSharp are documented here. The format is loosely based
 [semantic versioning](https://semver.org) — from 1.0.0 breaking changes only come with a major
 version (on the earlier 0.x releases, minor versions could carry them).
 
+## [1.0.1]
+
+Documentation-only release; no code changes.
+
+### Fixed
+
+- The NuGet package now carries a dedicated `README.nuget.md`: nuget.org renders a restricted
+  markdown where raw HTML is shown as text, so the GitHub README's HTML-centered logo appeared as
+  literal markup on the package page.
+
+### Added
+
+- `docs/USAGE.md` gains a **Publishing with Native AOT** section (enabling `PublishAot`, bringing
+  your own `JsonSerializerContext` for your own models, chaining `CoreJsonContext`) and examples for
+  the previously unillustrated reads: paging an address's signature history and walking a block,
+  data-driven priority fees (`getRecentPrioritizationFees` + `getFeeForMessage`), token account
+  balance and largest holders, and the node/cluster basics (health, version, block height,
+  transaction count, supply, slot leaders, blockhash validity).
+- README refreshed for the stable line: roadmap and per-assembly status column removed, Native AOT
+  moved to the top of the pitch, `samples/` added to the layout.
+
 ## [1.0.0]
 
 First stable release. The public API is now covered by the semver compatibility promise.

CLAUDE.md

@@ -4,7 +4,7 @@ A lean, modern .NET SDK for Solana: RPC + WebSocket streaming, wire-level transa
 signing/building. Optimised for low latency and a small dependency footprint — it is a
 deliberate, focused alternative to the heavier general-purpose SDKs, not a clone of them.
 
-Status: 1.0.0, first stable release (semver compatibility promise now applies to the public API). All four projects are in place: Core primitives (incl. a Borsh reader/writer), the Rpc client (reads + typed account state via `Mint`/`TokenAccount`/`NonceAccount` + Token-2022 extension decoding (`TokenExtensionSet`), `jsonParsed` transaction/block/account reads, the full current JSON-RPC HTTP read surface (deprecated getStakeActivation excluded), send/simulate, JSON-RPC batching via `RpcBatch`, typed transaction errors, multiplexed WebSocket streaming with auto-reconnect, DI + resilience), the Wallet (Ed25519 keys, signing, verification, key parsing, BIP-39/SLIP-0010 mnemonic derivation), and Programs (System/Token/ATA/Compute Budget/Memo + the Address Lookup Table program, PDA/ATA, legacy + v0 transaction building/signing/parsing, durable-nonce builder support, and instruction decompilation). As of 0.7.0 all JSON is source-generated (no reflection) and every assembly is Native AOT compatible (`IsAotCompatible`), with an AOT smoke sample published and run in CI. A separate live integration suite exercises the read and streaming paths against a real cluster.
+Status: 1.0.1, first stable release line (semver compatibility promise now applies to the public API). All four projects are in place: Core primitives (incl. a Borsh reader/writer), the Rpc client (reads + typed account state via `Mint`/`TokenAccount`/`NonceAccount` + Token-2022 extension decoding (`TokenExtensionSet`), `jsonParsed` transaction/block/account reads, the full current JSON-RPC HTTP read surface (deprecated getStakeActivation excluded), send/simulate, JSON-RPC batching via `RpcBatch`, typed transaction errors, multiplexed WebSocket streaming with auto-reconnect, DI + resilience), the Wallet (Ed25519 keys, signing, verification, key parsing, BIP-39/SLIP-0010 mnemonic derivation), and Programs (System/Token/ATA/Compute Budget/Memo + the Address Lookup Table program, PDA/ATA, legacy + v0 transaction building/signing/parsing, durable-nonce builder support, and instruction decompilation). As of 0.7.0 all JSON is source-generated (no reflection) and every assembly is Native AOT compatible (`IsAotCompatible`), with an AOT smoke sample published and run in CI. A separate live integration suite exercises the read and streaming paths against a real cluster.
 
 ## Commands
 
@@ -23,6 +23,7 @@ Run from the repo root (where `SolSharp.sln` lives):
 - **Attributes on their own line** — never inline with the member, e.g. `[JsonPropertyName("id")]` goes above the property, not beside it. `dotnet format` does not enforce this (only Rider does), so write it that way by hand.
 - **Target framework is `net8.0`.** Do not use net9-only APIs (e.g. `JsonStringEnumMemberName`, `InlineArray`-based span tricks that need newer ref-safety).
 - **Modern C# only.** File-scoped namespaces, `var`, collection expressions `[]`, primary constructors, switch expressions, pattern matching, `is null` / `is not null`. The full rule set lives in `.editorconfig` + `Directory.Build.props` — follow the analyzers, don't fight them. Do not restate style rules here.
+- **A feature is not done until it is documented.** Every user-facing addition or change lands in the same commit with all four documentation layers: (1) XML docs on the public API (enforced by CS1591 anyway); (2) `docs/USAGE.md` — a runnable example in the matching section (or a new section + `Contents` entry), with every snippet checked against the real signatures and model properties, not written from memory; (3) `README.md` — the wire-method list, feature bullets, and Layout if the shape of the repo changed (`README.nuget.md` only if the pitch/quick-start changes — it carries no method lists by design); (4) `CHANGELOG.md` under the release being prepared. Release-only extras: bump `Version` in `Directory.Build.props`, refresh `PackageReleaseNotes` in `src/SolSharp/SolSharp.csproj` (nuget.org shows only the current version's notes), and update the `Status:` line here.
 
 ## Architecture
 

Directory.Build.props

@@ -13,22 +13,18 @@
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
   </PropertyGroup>
 
-  <!-- Tests are exempt from the public-XML-docs rule; in library code a public member without docs
-       surfaces CS1591 and fails the CI build (-warnaserror). -->
   <PropertyGroup Condition="$(MSBuildProjectName.EndsWith('Tests'))">
     <NoWarn>$(NoWarn);CS1591</NoWarn>
   </PropertyGroup>
 
   <PropertyGroup Label="Package metadata">
-    <Version>1.0.0</Version>
+    <Version>1.0.1</Version>
     <Authors>Yevhen Koval</Authors>
     <Product>SolSharp</Product>
-    <!-- nuget.org search ranks by term relevance in id/title/tags/description, weighted by downloads;
-         the title and tags below carry the terms people actually search for. -->
     <Title>SolSharp — Solana SDK for .NET</Title>
     <Copyright>Copyright (c) 2026 Yevhen Koval</Copyright>
     <PackageLicenseExpression>MIT</PackageLicenseExpression>
-    <PackageReadmeFile>README.md</PackageReadmeFile>
+    <PackageReadmeFile>README.nuget.md</PackageReadmeFile>
     <PackageTags>solana;solana-sdk;web3;blockchain;rpc;websocket;wallet;spl-token;token-2022;transactions;ed25519;crypto;defi;nativeaot;aot;trimming;source-generators</PackageTags>
     <RepositoryType>git</RepositoryType>
     <RepositoryUrl>https://github.com/jecacs/SolSharp</RepositoryUrl>
@@ -48,7 +44,7 @@
   </PropertyGroup>
 
   <ItemGroup Condition="'$(IsPackable)' != 'false'">
-    <None Include="$(MSBuildThisFileDirectory)README.md" Pack="true" PackagePath="\" Visible="false" />
+    <None Include="$(MSBuildThisFileDirectory)README.nuget.md" Pack="true" PackagePath="\" Visible="false" />
     <None Include="$(MSBuildThisFileDirectory)assets/icon.png" Pack="true" PackagePath="\" Visible="false" Condition="Exists('$(MSBuildThisFileDirectory)assets/icon.png')" />
   </ItemGroup>
 

README.md

@@ -19,7 +19,7 @@ wire format and the signing path, without dragging in a large dependency graph.
 writing bots, indexers, or backend services that talk to Solana from .NET and care about
 speed and control, this is aimed at you.
 
-> **Status: 1.0.0 — stable release.** SolSharp ships as a single NuGet package — `SolSharp` —
+> **Status: 1.0.1 — stable release.** SolSharp ships as a single NuGet package — `SolSharp` —
 > bundling the Core (primitives + encodings), Wallet (Ed25519 keys, signing, verification, BIP-39/SLIP-0010
 > mnemonic import), Rpc (the full JSON-RPC HTTP read surface + send/simulate + WebSocket streaming + DI), and
 > Programs (instructions + transaction building + signing, durable nonces) assemblies. JSON is
@@ -28,7 +28,7 @@ speed and control, this is aimed at you.
 
 📖 **New here? Read the [usage guide](docs/USAGE.md)** — a task-oriented cookbook covering keys, reads,
 SPL token state, building/signing/sending transactions, v0 + address lookup tables, decoding transactions,
-WebSocket subscriptions, confirmation, and more.
+WebSocket subscriptions, confirmation, Native AOT publishing, and more.
 
 ## Motivation
 
@@ -61,23 +61,23 @@ dotnet add package SolSharp
 ```
 
 ```xml
-<PackageReference Include="SolSharp" Version="0.7.0" />
+<PackageReference Include="SolSharp" Version="1.0.1" />
 ```
 
-| Assembly           | Purpose                                              | Status |
-| ------------------ | --------------------------------------------------- | ------ |
-| `SolSharp.Core`    | Primitives, encoding, JSON, program/sysvar constants | Usable |
-| `SolSharp.Wallet`  | Ed25519 keys, key parsing, signing and verification | Usable |
-| `SolSharp.Rpc`     | HTTP JSON-RPC reads + WebSocket streaming + DI       | Usable |
-| `SolSharp.Programs`| Instructions (System/Token/ATA/Memo/Compute Budget/ALT) + transaction building | Usable |
+| Assembly           | Purpose                                              |
+| ------------------ | ---------------------------------------------------- |
+| `SolSharp.Core`    | Primitives, encoding, JSON, program/sysvar constants |
+| `SolSharp.Wallet`  | Ed25519 keys, key parsing, signing and verification  |
+| `SolSharp.Rpc`     | Full HTTP JSON-RPC read surface + WebSocket streaming + DI |
+| `SolSharp.Programs`| Instructions (System/Token/ATA/Memo/Compute Budget/ALT) + transaction building |
 
 Keeping the split in the source means the layering stays compiler-enforced — dependencies point downward
 only: `Rpc` and `Wallet` build on `Core`, and `Programs` builds on `Core` and `Wallet`. `Core` depends on
 nothing else in the solution and pulls no network or crypto package.
 
 See the [changelog](CHANGELOG.md) for what changed in each release.
 
-## What's here today
+## What's inside
 
 `SolSharp.Core`:
 
@@ -207,25 +207,6 @@ var tx = new TransactionBuilder()
 var signature = await rpc.SendTransactionAsync(tx.Serialize());
 ```
 
-## Roadmap
-
-- [x] Core primitives — `PublicKey`, `Base58`, `ShortVec`
-- [x] RPC enum + JSON converters (`Commitment`)
-- [x] Program / sysvar / mint constants + validation
-- [x] `SolSharp.Wallet` — Ed25519 keys, signing/verification, key parsing
-- [x] `SolSharp.Rpc` — HTTP reads (`getAccountInfo` / `getMultipleAccounts` / `getProgramAccounts` / `getSignaturesForAddress`, balances, blockhash, token supply, ...) + `sendTransaction` / `simulateTransaction`; multiplexed WebSocket streaming (slots, logs, accounts, programs, signatures, blocks) with auto-reconnect and optional `ILogger` diagnostics; DI + resilience
-- [x] `SolSharp.Programs` — System / Token (+ Token-2022) / ATA / Compute Budget / Memo instructions, PDA/ATA, transaction builder
-- [x] Versioned (v0) transactions + address lookup tables (compile / sign / fetch + decode / ALT program)
-- [x] Borsh reader + writer, typed SPL account state (`Mint` / `TokenAccount`), `Transaction.Deserialize` + instruction decompilation, and typed `TransactionError`
-- [x] Live integration test suite (configurable RPC / WS endpoint)
-- [x] Published NuGet package (single `SolSharp` package bundling the four assemblies)
-- [x] Durable nonces — nonce instructions + `NonceAccount` decoding + `TransactionBuilder.SetDurableNonce`
-- [x] Mnemonic wallet import — BIP-39 + SLIP-0010 (`solana-keygen` and Phantom/Solflare schemes)
-- [x] Token-2022 extensions — TLV decoding with typed views (transfer fee, metadata, delegate, ...)
-- [x] Devnet write gate — live airdrop / transfer / durable-nonce run before every release
-- [x] JSON-RPC batching, allocation-free (span) transaction serialization, `AddSolanaWs` DI
-- [x] BenchmarkDotNet harness (`benchmarks/`)
-
 ## Requirements
 
 - .NET 8 SDK or later.
@@ -271,6 +252,7 @@ SolSharp/
   src/SolSharp.Wallet/ Keypair (+ parsing), ISigner, PublicKey.Verify / IsOnCurve
   src/SolSharp.Programs/ instructions, PDA/ATA, Message/Transaction, TransactionBuilder
   src/SolSharp/        packaging facade — bundles the four assemblies into the single NuGet package
+  samples/             SolSharp.AotSmoke — native-compiled smoke sample, published and run in CI
   tests/               NUnit + FluentAssertions, mirroring each project
                        (+ SolSharp.IntegrationTests: live-cluster read/streaming checks)
   .github/workflows/   ci.yml (build + offline tests) and release.yml (tag → NuGet trusted publishing)

README.nuget.md

@@ -0,0 +1,65 @@
+# SolSharp
+
+A lean, modern, Native AOT-ready .NET SDK for Solana — RPC, WebSocket streaming, and
+wire-level transaction signing and building. No reflection anywhere: all JSON is
+source-generated, and every assembly compiles clean to a native binary.
+
+SolSharp is built for low latency and a small dependency footprint. If you are writing
+bots, indexers, or backend services that talk to Solana from .NET and care about speed
+and control, this is aimed at you.
+
+## Why SolSharp
+
+- **Native AOT ready.** Source-generated JSON (no reflection), trimmable, AOT-clean — ship a
+  self-contained native binary with instant startup. CI runs a native-compiled smoke test on every push.
+- **Full RPC coverage.** The complete current JSON-RPC HTTP read surface, send/simulate,
+  batching, and multiplexed WebSocket subscriptions with automatic reconnect.
+- **Wire-level control.** Spec-accurate legacy and v0 transaction building, signing, and decoding —
+  every encoding checked byte-for-byte against the Rust `solana-sdk`.
+- **Lean.** No kitchen-sink dependency graph; allocation-free hot paths and span-based APIs.
+
+## Quick start
+
+```csharp
+using SolSharp.Rpc;
+using SolSharp.Wallet;
+using SolSharp.Programs;
+
+// DI with a built-in resilience pipeline (or: new SolanaRpcClient(httpClient))
+services.AddSolanaRpc("https://your-rpc-endpoint");
+
+var lamports = await rpc.GetBalanceAsync(account);
+
+// Build, sign, and send a transfer
+using var payer = Keypair.Parse(secret);
+var blockhash = (await rpc.GetLatestBlockhashAsync()).Blockhash;
+
+var tx = new TransactionBuilder()
+    .SetRecentBlockhash(blockhash)
+    .AddInstruction(SystemProgram.Transfer(payer.PublicKey, recipient, 1_000_000))
+    .Build(payer);
+
+var signature = await rpc.SendAndConfirmTransactionAsync(tx.Serialize());
+```
+
+```csharp
+// WebSocket streaming
+await using var ws = new SolanaWsClient();
+await ws.ConnectAsync(new Uri("wss://your-rpc-endpoint"));
+await foreach (var slot in ws.SubscribeSlotsAsync())
+    Console.WriteLine(slot.Slot);
+```
+
+## Learn more
+
+- [Usage guide](https://github.com/jecacs/SolSharp/blob/main/docs/USAGE.md) — a task-oriented
+  cookbook: keys and mnemonic import, reads, SPL token state, priority fees, v0 + address lookup
+  tables, durable nonces, decoding transactions, subscriptions, batching, and confirmation.
+- [GitHub repository](https://github.com/jecacs/SolSharp)
+- [Changelog](https://github.com/jecacs/SolSharp/blob/main/CHANGELOG.md)
+
+## Security
+
+SolSharp handles private keys and builds transactions that move funds. It has **not** been audited —
+use at your own risk. Never hand a raw private key to a dependency you do not control: sign with your
+own signer and simulate before sending.