NEAR for Backend Devs: A Familiar Frontier

// ================================================================================================
// NEAR SMART CONTRACT: Twitter-like Social Media Platform
// ================================================================================================
//
// This smart contract implements a Twitter-like platform on the NEAR blockchain.
// For backend engineers new to blockchain, think of this as a REST API service that:
// - Stores data permanently on a distributed database (the blockchain)
// - Has no central server - it runs on hundreds of nodes worldwide
// - Charges small fees (gas) for write operations to prevent spam
// - Is immutable once deployed (like deploying code that can't be changed)
//
// Key NEAR/Blockchain Concepts for Backend Engineers:
// - Smart Contract = Your backend service logic that runs on blockchain
// - Account ID = User identifier (like username, but globally unique)
// - Gas = Computational cost (like AWS Lambda pricing, but for blockchain operations)
// - Storage = Persistent data (like a database, but decentralized and permanent)
// - View Methods = Read operations (free, like GET requests)
// - Call Methods = Write operations (cost gas, like POST/PUT/DELETE requests)

// Import NEAR SDK components - think of this as importing your web framework
use near_sdk::store::IterableMap; // Like HashMap but optimized for blockchain storage
use near_sdk::{env, near, AccountId, PanicOnDefault, Timestamp};

// ================================================================================================
// DATA STRUCTURES
// ================================================================================================

// Tweet represents a single tweet in our social media platform
// The #[near] attribute automatically handles serialization/deserialization
// Think of this as your API response/request DTOs, but for blockchain
#[near(serializers = [borsh, json])]
#[derive(Clone, Debug, PartialEq)]
pub struct Tweet {
    // Unique identifier for this tweet (like auto-increment ID in SQL)
    pub id: u64,

    // NEAR account that created this tweet (like user_id in traditional apps)
    // AccountId is NEAR's version of a username/user identifier
    pub author: AccountId,

    // The actual tweet content (like message body)
    pub text: String,

    // When this tweet was created (NEAR provides nanoseconds since Unix epoch)
    // Think of this as created_at timestamp in your database
    pub timestamp: Timestamp,

    // Number of likes this tweet has received (like a counter field)
    pub likes: u64,
}

// ================================================================================================
// SMART CONTRACT STATE
// ================================================================================================

// TwitterContract is the main contract state - think of this as your application's
// in-memory state that persists between requests (like instance variables in a service class)
//
// In traditional backend:
// - You'd have a database to store tweets
// - You'd have application state in memory/cache
//
// In NEAR:
// - Contract state IS your database (stored on blockchain)
// - State persists between function calls
// - State is automatically loaded/saved by NEAR runtime
#[near(contract_state)]
#[derive(PanicOnDefault)] // Prevents accidental initialization without proper setup
pub struct TwitterContract {
    // Storage for all tweets - like your main tweets table
    // IterableMap is NEAR's version of HashMap optimized for blockchain storage
    // Key: tweet_id, Value: Tweet object
    tweets: IterableMap<u64, Tweet>,

    // Counter for generating unique tweet IDs (like auto-increment in SQL)
    // This ensures each tweet gets a unique identifier
    next_tweet_id: u64,
}

// ================================================================================================
// CONTRACT IMPLEMENTATION
// ================================================================================================

// The #[near] attribute marks this implementation block as containing contract methods
// Think of these as your REST API endpoints, but they run on the blockchain
#[near]
impl TwitterContract {
    // ============================================================================================
    // INITIALIZATION METHOD
    // ============================================================================================

    // Contract constructor - called once when the contract is first deployed
    // Similar to database migrations or initial setup in traditional backends
    // The #[init] attribute marks this as the initialization method
    #[init]
    pub fn new() -> Self {
        Self {
            // Initialize tweet storage with a unique storage prefix
            // "b't'" is a byte string prefix to avoid storage conflicts
            // Think of this as creating a table in your database
            tweets: IterableMap::new(b"t"),

            // Start tweet IDs from 0
            next_tweet_id: 0,
        }
    }

    // ============================================================================================
    // WRITE METHODS (Cost gas, modify state)
    // ============================================================================================

    // Post a new tweet - equivalent to POST /tweets endpoint
    // This is a "call" method that modifies state and costs gas
    pub fn post_tweet(&mut self, text: String) -> Tweet {
        // Get the account that called this method (like extracting user from JWT token)
        // env::predecessor_account_id() returns who made the transaction
        let author = env::predecessor_account_id();

        // Get current blockchain timestamp (like System.currentTimeMillis() in Java)
        // NEAR provides nanoseconds since Unix epoch
        let timestamp = env::block_timestamp();

        // Generate unique ID for this tweet (like auto-increment primary key)
        let tweet_id = self.next_tweet_id;

        // Create the tweet object (like building your entity/model)
        let new_tweet = Tweet {
            id: tweet_id,
            author: author.clone(),
            text,
            timestamp,
            likes: 0, // New tweets start with 0 likes
        };

        // Store the tweet in our "database" (contract storage)
        // This is like INSERT INTO tweets (...) VALUES (...)
        self.tweets.insert(tweet_id, new_tweet.clone());

        // Increment ID counter for next tweet (like auto-increment)
        self.next_tweet_id += 1;

        // Log the action - similar to application logging
        // These logs are stored on blockchain and can be queried
        env::log_str(&format!(
            "Tweet #{} posted by @{} at {}",
            tweet_id, author, timestamp
        ));

        // Return the created tweet (like returning the entity in REST API)
        new_tweet
    }

    // Like a tweet - equivalent to POST /tweets/{id}/like endpoint
    // This modifies state (increments like counter) so it costs gas
    pub fn like_tweet(&mut self, tweet_id: u64) -> Option<Tweet> {
        // Try to get a mutable reference to the tweet
        // This is like: SELECT * FROM tweets WHERE id = ? FOR UPDATE
        if let Some(tweet) = self.tweets.get_mut(&tweet_id) {
            // Increment the like counter (like UPDATE tweets SET likes = likes + 1)
            tweet.likes += 1;

            // Log the like action for transparency/debugging
            env::log_str(&format!(
                "Tweet #{} liked by @{}. Total likes: {}",
                tweet_id,
                env::predecessor_account_id(), // Who liked the tweet
                tweet.likes
            ));

            // Return the updated tweet (clone because we need to return owned data)
            Some(tweet.clone())
        } else {
            // Tweet doesn't exist - log the attempt
            // In REST API, this would be a 404 Not Found
            env::log_str(&format!(
                "Attempt to like non-existent tweet #{} by @{}",
                tweet_id,
                env::predecessor_account_id()
            ));
            None
        }
    }

    // Delete a tweet - equivalent to DELETE /tweets/{id} endpoint
    // Only the tweet author can delete their own tweets (authorization check)
    pub fn delete_tweet(&mut self, tweet_id: u64) {
        // Get who's trying to delete the tweet (like checking JWT/session)
        let caller = env::predecessor_account_id();

        // Check if tweet exists and verify ownership
        // This is like: SELECT author FROM tweets WHERE id = ?
        if let Some(tweet) = self.tweets.get(&tweet_id) {
            // Authorization check - only author can delete their tweet
            // Similar to checking if user owns the resource in REST API
            if tweet.author == caller {
                // Delete the tweet from storage
                // Like: DELETE FROM tweets WHERE id = ?
                self.tweets.remove(&tweet_id);
                env::log_str(&format!("Tweet #{} deleted by @{}", tweet_id, caller));
            } else {
                // Unauthorized deletion attempt - log security event
                // In REST API, this would be 403 Forbidden
                env::log_str(&format!(
                    "User @{} attempted to delete tweet #{} but is not the author.",
                    caller, tweet_id
                ));
            }
        } else {
            // Tweet doesn't exist - log the attempt
            // In REST API, this would be 404 Not Found
            env::log_str(&format!(
                "Attempt to delete non-existent tweet #{} by @{}",
                tweet_id, caller
            ));
        }
    }

    // ============================================================================================
    // READ METHODS (Free, don't modify state)
    // ============================================================================================
    // These are "view" methods - they don't cost gas and don't modify contract state
    // Think of these as GET endpoints in your REST API

    // Get all tweets with pagination - like GET /tweets?offset=0&limit=10
    // from_index: starting position (like OFFSET in SQL)
    // limit: maximum number of tweets to return (like LIMIT in SQL)
    pub fn get_all_tweets(&self, from_index: Option<u64>, limit: Option<u64>) -> Vec<Tweet> {
        // Set default values if not provided (common REST API pattern)
        let start = from_index.unwrap_or(0);
        let limit_val = limit.unwrap_or(10);

        // Query tweets with pagination (like SELECT * FROM tweets LIMIT x OFFSET y)
        self.tweets
            .iter() // Iterate over all tweets
            .skip(start as usize) // Skip 'start' number of tweets (OFFSET)
            .take(limit_val as usize) // Take only 'limit_val' tweets (LIMIT)
            .map(|(_key, tweet)| tweet.clone()) // Extract tweet objects (ignore keys)
            .collect() // Collect into Vector to return
    }

    // Get specific tweet by ID - like GET /tweets/{id}
    pub fn get_tweet_by_id(&self, tweet_id: u64) -> Option<Tweet> {
        // Simple lookup by primary key
        // Like: SELECT * FROM tweets WHERE id = ?
        self.tweets.get(&tweet_id).cloned()
    }

    // Get tweets by specific author with pagination - like GET /users/{id}/tweets
    // This demonstrates filtering in blockchain storage (no SQL WHERE clause available)
    pub fn get_tweets_by_author(
        &self,
        author_id: AccountId,
        from_index: Option<u64>,
        limit: Option<u64>,
    ) -> Vec<Tweet> {
        let start = from_index.unwrap_or(0);
        let limit_val = limit.unwrap_or(10);

        // We need to manually filter since blockchain storage doesn't have SQL-like queries
        // This is like doing: SELECT * FROM tweets WHERE author = ? LIMIT x OFFSET y
        // But we have to iterate through all tweets and filter manually
        let mut author_tweets = Vec::new();
        let mut count = 0;
        let mut current_index = 0;

        // Iterate through all tweets to find matches
        for (_id, tweet) in self.tweets.iter() {
            // Check if this tweet belongs to the requested author
            if tweet.author == author_id {
                // Apply pagination logic
                if current_index >= start && count < limit_val {
                    author_tweets.push(tweet.clone());
                    count += 1;
                }
                current_index += 1;
            }

            // Optimization: stop early if we've found enough tweets
            if count >= limit_val && current_index > start {
                break;
            }
        }

        author_tweets
    }
}

// ================================================================================================
// KEY DIFFERENCES FROM TRADITIONAL BACKEND:
// ================================================================================================
//
// 1. STATE PERSISTENCE:
//    - Traditional: Use database, cache, session storage
//    - NEAR: Contract state IS your database, automatically persisted
//
// 2. USER AUTHENTICATION:
//    - Traditional: JWT tokens, sessions, OAuth
//    - NEAR: Cryptographic signatures, account-based auth built-in
//
// 3. SCALABILITY:
//    - Traditional: Horizontal scaling, load balancers, microservices
//    - NEAR: Automatic scaling across blockchain network
//
// 4. COSTS:
//    - Traditional: Server costs, database costs, bandwidth
//    - NEAR: Gas fees for computations, storage costs per byte
//
// 5. DEPLOYMENT:
//    - Traditional: CI/CD pipelines, blue-green deployments
//    - NEAR: Deploy once, immutable (or upgradeable with special patterns)
//
// 6. DATA CONSISTENCY:
//    - Traditional: ACID transactions, eventual consistency
//    - NEAR: Atomic transactions guaranteed by blockchain consensus
//
// 7. QUERYING DATA:
//    - Traditional: SQL, NoSQL query languages
//    - NEAR: Manual iteration, no complex queries (design for simple access patterns)