docs: update contributing guide and developer documentation

CONTRIBUTING.md

@@ -0,0 +1,96 @@
+# Contributing to starknet.go
+
+Thank you for your interest in contributing to starknet.go!
+
+## Prerequisites
+
+- Go 1.25 or higher
+- Make
+
+## Setup Development Environment
+
+1. Clone the repository:
+```bash
+git clone https://github.com/NethermindEth/starknet.go.git
+cd starknet.go
+```
+
+2. Install development dependencies:
+```bash
+make install-deps
+```
+
+This installs:
+- golangci-lint v2.7.2 - for linting
+- mockgen v0.6.0 - for generating mocks
+
+## Running Tests
+
+### Test Environments
+
+The SDK supports multiple test environments:
+
+| Environment | Command             | Description                          |
+|-------------|---------------------|--------------------------------------|
+| Mock        | `make mock-test`    | Unit tests with mocked RPC responses |
+| Devnet      | `make devnet-test`  | Tests against local devnet           |
+| Testnet     | `make testnet-test` | Tests against Starknet testnet       |
+| Mainnet     | `make mainnet-test` | Tests against Starknet mainnet       |
+| All         | `make test`         | Run all tests                        |
+
+### Running Specific Tests
+
+```bash
+# Run tests for specific package
+go test -v ./rpc/...
+go test -v ./account/...
+go test -v ./utils/...
+
+# Run with specific environment
+go test -v ./rpc/... -env testnet
+```
+
+## Linting
+
+Run linter before submitting PR:
+
+```bash
+make lint
+```
+
+This runs golangci-lint with auto-fix enabled. Configuration is in `.golangci.yaml`.
+
+## Code Style
+
+- Follow standard Go conventions
+- Use gofmt for formatting (handled by linter)
+- Add comments for exported functions
+- Write unit tests for new functionality
+
+## Submitting Changes
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/your-feature`
+3. Make your changes
+4. Run tests: `make test`
+5. Run linter: `make lint`
+6. Commit with descriptive message
+7. Push and create Pull Request
+
+## Pull Request Guidelines
+
+- Describe what the PR does
+- Reference related issues
+- Include test coverage for new code
+- Ensure all CI checks pass
+
+## Documentation
+
+When updating documentation, follow the rules in `docs/DOCUMENTATION_RULES.md`:
+- Always verify struct definitions against source code
+- Include GitHub source links
+- Test that code examples compile
+
+## Questions?
+
+Open an issue or reach out to maintainers.

docs/README.md

@@ -1 +1,7 @@
 This is a [Vocs](https://vocs.dev) project bootstrapped with the Vocs CLI.
+
+## Development
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for contribution guidelines.
+
+See [developers.md](./developers.md) for project structure and development workflow.

docs/developers.md

@@ -0,0 +1,153 @@
+# Developer Guide
+
+This guide explains the starknet.go project structure and development workflow.
+
+## Project Structure
+
+```
+starknet.go/
+├── account/       # Account management
+├── client/        # RPC client infrastructure
+├── contracts/     # Contract utilities
+├── curve/         # Cryptographic operations
+├── devnet/        # Devnet integration
+├── docs/          # Documentation (Vocs-based)
+├── examples/      # Usage examples
+├── hash/          # Hashing utilities
+├── internal/      # Internal utilities
+├── merkle/        # Merkle tree operations
+├── paymaster/     # Paymaster integration
+├── rpc/           # RPC types and provider
+├── typeddata/     # Typed data signing
+└── utils/         # Utility functions
+```
+
+## Package Descriptions
+
+### `rpc/`
+Core RPC functionality:
+- `Provider` - main RPC client for Starknet nodes
+- Type definitions for blocks, transactions, events
+- WebSocket support for subscriptions
+
+### `account/`
+Account management:
+- Account creation and import
+- Transaction signing
+- Nonce management
+- Multi-call support
+
+### `client/`
+Low-level client infrastructure:
+- HTTP/WebSocket client
+- Error handling (`rpcerr/`)
+- Logging (`log/`)
+
+### `utils/`
+Utility functions:
+- Felt conversions (`HexToFelt`, `FeltToHex`)
+- Selector generation (`GetSelectorFromNameFelt`)
+- Transaction utilities
+
+### `hash/`
+Cryptographic hashing:
+- Pedersen hash
+- Poseidon hash
+
+### `typeddata/`
+Typed data for off-chain signing (similar to EIP-712)
+
+### `paymaster/`
+Paymaster integration for sponsored transactions
+
+### `examples/`
+Working examples demonstrating SDK usage:
+- `deployAccount/` - Account deployment
+- `invoke/` - Transaction invocation
+- `readEvents/` - Event filtering
+- `simpleCall/` - Contract calls
+- `websocket/` - WebSocket subscriptions
+
+## Development Workflow
+
+### 1. Setup
+```bash
+make install-deps
+```
+
+### 2. Make Changes
+Edit code in relevant package.
+
+### 3. Test
+```bash
+# Quick feedback with mock tests
+make mock-test
+
+# Full test against devnet
+make devnet-test
+```
+
+### 4. Lint
+```bash
+make lint
+```
+
+### 5. Submit PR
+Create a pull request with your changes.
+
+## Testing Strategy
+
+### Mock Tests
+- Located alongside source files (`*_test.go`)
+- Use mocked RPC responses
+- Fast, no network required
+- Run with: `make mock-test`
+
+### Integration Tests
+- Test against real Starknet nodes
+- Require environment configuration
+- Run with: `make devnet-test`, `make testnet-test`, `make mainnet-test`
+
+### Test Data
+- `testData/` folders contain fixtures
+- JSON files with sample responses
+
+## Makefile Commands
+
+| Command                | Description                     |
+|------------------------|---------------------------------|
+| `make test`            | Run all tests                   |
+| `make mock-test`       | Run mock tests only             |
+| `make devnet-test`     | Run devnet integration tests    |
+| `make testnet-test`    | Run testnet integration tests   |
+| `make mainnet-test`    | Run mainnet integration tests   |
+| `make lint`            | Run golangci-lint with auto-fix |
+| `make install-deps`    | Install dev dependencies        |
+| `make clean-testcache` | Clear Go test cache             |
+
+## Dependencies
+
+### Required
+- Go 1.25+
+- Make
+
+### Development Tools
+- golangci-lint v2.7.2 - Linting
+- mockgen v0.6.0 - Mock generation
+
+Install with:
+```bash
+make install-deps
+```
+
+## Environment Variables
+
+For integration tests, create a `.env` file in `examples/internal/`:
+
+```bash
+# RPC URLs
+INTEGRATION_BASE=https://your-rpc-url
+WS_INTEGRATION_BASE=wss://your-ws-url
+```
+
+See existing examples in `examples/` for reference.