docs: Enhance SDK documentation and examples

- Update stream lifecycle documentation with correct timestamp handling
- Improve stream deletion and resource management explanations
- Refactor code examples to match current SDK implementation
- Add detailed guidance on stream creation, management, and deletion
- Ensure consistency across API reference, examples, and core documentation
- Clarify stream types, permissions, and best practices
- Improve error handling and transaction management guidance

Key improvements:
- Corrected date/timestamp usage in examples
- Added comprehensive stream deletion examples
- Updated API reference with precise method descriptions
- Enhanced documentation for primitive and composed streams
- Provided clearer explanations of stream lifecycle and permissions

Author: MicBun

README.md

@@ -41,7 +41,7 @@ go get github.com/trufnetwork/sdk-go
    task single:start
    ```
 
-   **Note:** Setting up a local node as described above will initialize an empty database. This setup is primarily for testing the technology or development purposes. If you are a node operator and wish to sync with the Truf Network to access real data, please follow the [Node Operator Guide](https://github.com/trufnetwork/node/blob/main/docs/node-operator-guide.md) for instructions on connecting to the network and syncing data.
+   **Note:** Setting up a local node as described above will initialize an empty database. This setup is primarily for testing the technology or development purposes. If you are a node operator and wish to sync with the TRUF.NETWORK to access real data, please follow the [Node Operator Guide](https://github.com/trufnetwork/node/blob/main/docs/node-operator-guide.md) for instructions on connecting to the network and syncing data.
 
 4. **Verify Node Synchronization**
 
@@ -176,7 +176,7 @@ func main() {
 	}
 
 	// Now you can perform operations on the mainnet
-	fmt.Println("Connected to Truf Network Mainnet")
+	fmt.Println("Connected to TRUF.NETWORK Mainnet")
 }
 ```
 
@@ -229,3 +229,235 @@ For additional support or questions, please [open an issue](https://github.com/t
 
 The SDK-Go repository is licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE.md) for more details.
 
+## Stream Creation and Management
+
+The TN SDK provides comprehensive support for creating and managing both primitive and composed streams. 
+
+### Primitive Streams
+
+Primitive streams are raw data sources that can represent various types of data points. To create a primitive stream:
+
+```go
+// Generate a unique stream ID
+primitiveStreamId := util.GenerateStreamId("my-market-data-stream")
+
+// Deploy the primitive stream
+deployTx, err := tnClient.DeployStream(ctx, primitiveStreamId, types.StreamTypePrimitive)
+
+// Insert records into the primitive stream
+primitiveActions, err := tnClient.LoadPrimitiveActions()
+insertTx, err := primitiveActions.InsertRecords(ctx, []types.InsertRecordInput{
+    {
+        DataProvider: dataProviderAddress,
+        StreamId:     primitiveStreamId.String(),
+        EventTime:    int(time.Now().Unix()),
+        Value:        100.5,
+    },
+})
+```
+
+### Composed Streams
+
+Composed streams aggregate and process data from multiple primitive or other composed streams. They use a taxonomy to define how child streams are combined:
+
+```go
+// Deploy a composed stream
+composedStreamId := util.GenerateStreamId("my-composite-index")
+deployTx, err := tnClient.DeployStream(ctx, composedStreamId, types.StreamTypeComposed)
+
+// Load composed actions
+composedActions, err := tnClient.LoadComposedActions()
+
+// Set taxonomy (define how child streams are combined)
+taxonomyTx, err := composedActions.InsertTaxonomy(ctx, types.Taxonomy{
+    ParentStream: tnClient.OwnStreamLocator(composedStreamId),
+    TaxonomyItems: []types.TaxonomyItem{
+        {
+            ChildStream: tnClient.OwnStreamLocator(primitiveStreamId1),
+            Weight:      0.6, // 60% weight
+        },
+        {
+            ChildStream: tnClient.OwnStreamLocator(primitiveStreamId2),
+            Weight:      0.4, // 40% weight
+        },
+    },
+})
+```
+
+### Complex Stream Creation Example
+
+For a comprehensive example demonstrating stream creation, taxonomy setup, and data retrieval, see the `examples/complex_stream_example/main.go` file. This example shows:
+
+- Deploying primitive streams
+- Inserting records into primitive streams
+- Creating a composed stream
+- Setting up stream taxonomy
+- Retrieving composed stream records
+
+Key steps include:
+1. Generating unique stream IDs
+2. Deploying primitive and composed streams
+3. Inserting records into primitive streams
+4. Defining stream taxonomy
+5. Retrieving composed stream records
+
+This example provides a practical walkthrough of creating and managing streams in the TRUF.NETWORK ecosystem.
+
+### Stream Locators and Data Providers
+
+#### Stream Locators
+
+A `StreamLocator` is a unique identifier for a stream that consists of two key components:
+1. `StreamId`: A unique identifier for the stream
+2. `DataProvider`: The Ethereum address of the stream's creator/owner
+
+The `OwnStreamLocator()` method is a convenience function that automatically creates a `StreamLocator` using:
+- The provided `StreamId`
+- The current client's Ethereum address
+
+Example:
+```go
+// Creates a StreamLocator with:
+// - The given stream ID
+// - The current client's address as the data provider
+streamLocator := tnClient.OwnStreamLocator(myStreamId)
+```
+
+This is particularly useful when you're creating and managing your own streams, as it automatically uses your client's address.
+
+#### Data Providers
+
+A `DataProvider` is the Ethereum address responsible for creating and managing a stream. When inserting records or performing operations on a stream, you need to specify the data provider's address.
+
+To get the current client's address, use:
+```go
+// Get the current client's Ethereum address
+dataProviderAddress := tnClient.Address()
+
+// Get the address as a string for use in stream operations
+dataProviderAddressString := dataProviderAddress.Address()
+```
+
+Key differences:
+- `tnClient.Address()` returns an `EthereumAddress` object
+- `dataProviderAddress.Address()` returns the address as a string, which is used in stream operations
+
+### Example of Stream Creation with Locators and Providers
+
+```go
+// Generate a stream ID
+streamId := util.GenerateStreamId("my-stream")
+
+// Deploy the stream using the current client's address
+deployTx, err := tnClient.DeployStream(ctx, streamId, types.StreamTypePrimitive)
+
+// Create a stream locator
+streamLocator := tnClient.OwnStreamLocator(streamId)
+
+// Get the data provider address
+dataProvider := tnClient.Address()
+
+// Insert a record using the data provider address
+insertTx, err := primitiveActions.InsertRecords(ctx, []types.InsertRecordInput{
+    {
+        DataProvider: dataProvider.Address(),
+        StreamId:     streamId.String(),
+        EventTime:    int(time.Now().Unix()),
+        Value:        100.5,
+    },
+})
+```
+
+This approach ensures that:
+- Streams are uniquely identified
+- Records are correctly attributed to their creator
+- Stream operations are performed with the correct addressing
+
+### Stream Deletion and Resource Management
+
+#### Why Delete Streams?
+
+Stream deletion is crucial for:
+- Cleaning up unused or test streams
+- Managing resource consumption
+- Maintaining a clean and organized stream ecosystem
+
+#### Stream Deletion Process
+
+Streams can be deleted using the `DestroyStream()` method:
+
+```go
+// Destroy a specific stream
+destroyTx, err := tnClient.DestroyStream(ctx, streamId)
+if err != nil {
+    // Handle deletion error
+    log.Printf("Failed to destroy stream: %v", err)
+}
+
+// Wait for the destroy transaction to be mined
+_, err = tnClient.WaitForTx(ctx, destroyTx, time.Second*5)
+if err != nil {
+    log.Printf("Error waiting for stream destruction: %v", err)
+}
+```
+
+#### Best Practices for Stream Deletion
+
+1. **Cleanup in Reverse Order**
+   - Delete composed streams before their child primitive streams
+   - Ensures proper resource management and prevents orphaned references
+
+2. **Error Handling**
+   - Always check for errors during stream deletion
+   - Log and handle potential issues gracefully
+
+3. **Deferred Deletion**
+   - Use `defer` for automatic cleanup in test or example scenarios
+   - Ensures resources are freed even if an error occurs
+
+Example of Deferred Stream Deletion:
+```go
+func main() {
+    // Defer stream destruction
+    defer func() {
+        streamIds := []util.StreamId{
+            composedStreamId,
+            primitiveStreamId1,
+            primitiveStreamId2,
+        }
+
+        for _, streamId := range streamIds {
+            destroyTx, err := tnClient.DestroyStream(ctx, streamId)
+            if err != nil {
+                log.Printf("Failed to destroy stream %s: %v", streamId, err)
+                continue
+            }
+
+            // Wait for the destroy transaction
+            _, err = tnClient.WaitForTx(ctx, destroyTx, time.Second*5)
+            if err != nil {
+                log.Printf("Error waiting for destroy transaction: %v", err)
+            }
+        }
+    }()
+
+    // Rest of the stream creation and management code
+}
+```
+
+#### Considerations
+
+- Stream deletion is a permanent action
+- Deleted streams cannot be recovered
+- Ensure you have the necessary permissions to delete a stream
+- In production, implement additional safeguards before deletion
+
+### When to Delete Streams
+
+- After completing testing
+- When streams are no longer needed
+- To free up resources
+- As part of a stream lifecycle management strategy
+
+By following these guidelines, you can effectively manage stream resources in the TRUF.NETWORK ecosystem.
+

docs/api-reference/api-reference.md

@@ -1,80 +1,80 @@
 # API Reference
 
-The Truf Node SDK offers a comprehensive set of APIs for interacting with the TN, allowing developers to create, manage, and consume data streams. This document provides detailed descriptions of all available methods in the SDK, along with examples of their usage.
+## TRUF.NETWORK SDK Overview
+
+The TRUF.NETWORK SDK provides a comprehensive toolkit for developers to interact with decentralized data streams. It enables seamless creation, management, and consumption of economic and financial data streams.
+
+### Key Features
+- Stream creation and management
+- Primitive and composed stream support
+- Flexible data retrieval
+- Advanced permission management
+- Secure, blockchain-backed data streams
 
 ## Interfaces
-- [Client](client.md)
-- [Primitive Stream](primitive-stream.md)
-- [Composed Stream](composed-stream.md)
 
-Other utilities are in the [util](util.md) documentation.
+The SDK is structured around several key interfaces:
 
-## Example Usage
+- [Client](client.md): Primary entry point for network interactions
+- [Primitive Stream](primitive-stream.md): Raw data stream management
+- [Composed Stream](composed-stream.md): Aggregated data stream handling
+
+## Core Concepts
+
+### Streams
+- **Primitive Streams**: Direct data sources with raw data points
+- **Composed Streams**: Aggregated streams combining multiple data sources
 
-Below is an example demonstrating how to use the TN SDK to deploy, initialize, and read from a primitive stream.
+### Data Management
+- Secure, immutable data recording
+- Flexible querying and indexing
+- Granular access control
+
+## Example Usage
 
 ```go
 package main
 
 import (
 	"context"
-	"fmt"
-	"github.com/golang-sql/civil"
-	"github.com/kwilteam/kwil-db/core/crypto"
-	"github.com/kwilteam/kwil-db/core/crypto/auth"
 	"github.com/trufnetwork/sdk-go/core/tnclient"
 	"github.com/trufnetwork/sdk-go/core/types"
 	"github.com/trufnetwork/sdk-go/core/util"
-	"time"
 )
 
 func main() {
-	// handle errors appropriately in a real application
 	ctx := context.Background()
 
-	// Create TN client
-	pk, _ := crypto.Secp256k1PrivateKeyFromHex("<your-private-key-hex>")
-	signer := &auth.EthPersonalSigner{Key: *pk}
-	tnClient, _ := tnclient.NewClient(ctx, "<https://tsn-provider-url.com>", tnclient.WithSigner(signer))
-
-	// Generate a stream ID
-	streamId := util.GenerateStreamId("example-stream")
-
-	// Deploy a new primitive stream
-	deployTxHash, _ := tnClient.DeployStream(ctx, streamId, types.StreamTypePrimitive)
-
-	// Wait for the transaction to be mined
-	txRes, _ := tnClient.WaitForTx(ctx, deployTxHash, time.Second)
-
-	// Load the deployed stream
-	stream, _ := tnClient.LoadPrimitiveStream(tnClient.OwnStreamLocator(streamId))
-
-	// Initialize the stream
-	txHashInit, _ := stream.InitializeStream(ctx)
-
-	// Wait for the initialization transaction to be mined
-	txResInit, _ := tnClient.WaitForTx(ctx, txHashInit, time.Second)
-	fmt.Println("Initialize transaction result:", txResInit)
-
-	// Insert records into the stream
-	txHashInsert, _ := stream.InsertRecords(ctx, []types.InsertRecordInput{
-		{
-			Value:     1,
-			DateValue: civil.Date{Year: 2023, Month: 1, Day: 1},
-		},
-	})
+	// Initialize client with mainnet endpoint
+	tnClient, err := tnclient.NewClient(
+		ctx, 
+		"https://gateway.mainnet.truf.network",
+		tnclient.WithSigner(mySigner),
+	)
+	if err != nil {
+		// Handle client initialization error
+	}
+
+	// Deploy a primitive stream
+	streamId := util.GenerateStreamId("my-economic-stream")
+	deployTx, err := tnClient.DeployStream(
+		ctx, 
+		streamId, 
+		types.StreamTypePrimitive,
+	)
+	// Handle deployment and further stream operations
+}
+```
 
-	// Wait for the insert transaction to be mined
-	_, _ = tnClient.WaitForTx(ctx, txHashInsert, time.Second)
+## Getting Started
 
-	// Read records from the stream
-	records, _ := stream.GetRecord(ctx, types.GetRecordInput{
-		DateFrom: civil.ParseDate("2023-01-01"),
-		DateTo:   civil.ParseDate("2023-01-31"),
-	})
-	fmt.Println("Records:", records)
-}
+1. Install the SDK
+2. Configure your network endpoint
+3. Initialize a client
+4. Create and manage streams
 
-```
+## Support and Community
 
-Please refer to the test files in the SDK repository for more examples and detailed usage patterns. These tests provide comprehensive examples of various stream operations and error-handling scenarios.
+- [GitHub Repository](https://github.com/trufnetwork/sdk-go)
+- [Issue Tracker](https://github.com/trufnetwork/sdk-go/issues)
+- [Documentation](https://docs.truf.network)