// Package storage provides a unified interface for sovereign data storage
// in Tutus blockchain deployments.
//
// # Overview
//
// Tutus is designed for government blockchain deployments where data sovereignty
// is critical. Different nations have different data residency requirements:
//
//   - GDPR requires EU citizen data to remain in the EU
//   - China's Cybersecurity Law requires data localization
//   - Russia's Federal Law 242-FZ mandates domestic storage
//   - Many nations have sector-specific requirements (healthcare, finance)
//
// The storage package provides a pluggable architecture that allows each
// government deployment to choose storage backends that comply with their
// legal requirements.
//
// # Supported Providers
//
// The following storage providers are available:
//
//   - neofs: NeoFS decentralized storage (can be private or public)
//   - local: Local filesystem (for single-node or NAS deployments)
//   - s3: S3-compatible storage (AWS, Azure, GCP, sovereign clouds)
//
// Additional providers can be implemented by satisfying the Provider interface.
//
// # Usage
//
// Basic usage with the registry:
//
//	registry := storage.NewRegistry()
//	registry.Register(neofs.New(cfg.NeoFS))
//	registry.Register(local.New(cfg.Local))
//
//	provider, ok := registry.Get("neofs")
//	if !ok {
//	    log.Fatal("provider not found")
//	}
//
//	id, err := provider.Put(ctx, data, storage.PutOptions{})
//	if err != nil {
//	    log.Fatal(err)
//	}
//
// # Block Storage
//
// For blockchain-specific operations, use the BlockStorage interface:
//
//	bs := neofs.NewBlockStorage(cfg)
//	id, err := bs.PutBlock(ctx, blockIndex, blockData)
//	block, err := bs.GetBlock(ctx, blockIndex)
//
// # State Storage
//
// For state snapshots, use the StateStorage interface:
//
//	ss := local.NewStateStorage(cfg)
//	id, err := ss.PutState(ctx, height, stateData)
//	state, err := ss.GetState(ctx, height)
//
// # Configuration
//
// Storage is configured in the node configuration file:
//
//	storage:
//	  provider: neofs
//	  neofs:
//	    endpoints:
//	      - "grpc://neofs.example.gov:8080"
//	    container: "7s23kG4..."
//	    timeout: 30s
//	  local:
//	    path: /var/lib/tutus/storage
//	  s3:
//	    endpoint: "s3.sovereign-cloud.gov"
//	    bucket: "tutus-blocks"
//	    region: "national-1"
//
// # Data Sovereignty
//
// When deploying Tutus for a government:
//
//  1. Assess data residency requirements for the jurisdiction
//  2. Choose storage providers that comply (sovereign cloud, on-premises, etc.)
//  3. Configure network policies to prevent cross-border data transfer
//  4. Enable encryption at rest and in transit
//  5. Implement access controls per government security standards
//
// For NeoFS in sovereign deployments, run a private NeoFS network within
// the nation's infrastructure rather than using the public network.
package storage