Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 1 addition & 17 deletions .pre-commit-config.yaml
Original file line number Diff line number Diff line change
@@ -1,7 +1,5 @@
# PropChain Pre-commit Configuration
# This file configures pre-commit hooks for code quality and consistency.
# See docs/code-style-guide.md for the rationale behind each hook.
# To install: ./scripts/setup-pre-commit.sh
# This file configures pre-commit hooks for code quality and consistency

repos:
# Rust formatting and linting
Expand Down Expand Up @@ -104,20 +102,6 @@ repos:
args: [--no-deps, --document-private-items]
pass_filenames: false

- id: cargo-audit
name: cargo audit (dependency CVEs)
entry: cargo audit
language: system
args: [--deny, warnings]
pass_filenames: false

- id: cargo-deny
name: cargo deny (license & dependency policy)
entry: cargo deny
language: system
args: [check]
pass_filenames: false

# Configuration for specific hooks
default_language_version:
python: python3
Expand Down
82 changes: 20 additions & 62 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,14 @@

Thank you for your interest in contributing to PropChain Smart Contracts! This guide will help you get started with contributing to our Rust-based smart contract system.

> **Documentation Version**: 2.0.0 — Updated March 2026

## 🚀 Getting Started

### Prerequisites

Before you start contributing, make sure you have:

- **Rust** 1.75+ installed with stable toolchain (pinned in `rust-toolchain.toml`)
- **cargo-contract** 3.x CLI for ink! smart contract development
- **Rust** 1.70+ installed with stable toolchain
- **cargo-contract** CLI for ink! smart contract development
- **Git** for version control
- Basic understanding of **Rust** and **ink!** framework
- Familiarity with **Substrate/Polkadot** ecosystem
Expand All @@ -29,25 +27,19 @@ Before you start contributing, make sure you have:
```bash
# Install Rust (if not already installed)
curl https://sh.rustup.rs -sSf | sh

# Install cargo-contract
cargo install cargo-contract --locked --version "^3"

cargo install cargo-contract --locked
# Add WASM target
rustup target add wasm32-unknown-unknown

# Optional: dependency auditing tools
cargo install cargo-deny cargo-audit
```

3. **Set up your development environment**
```bash
# Install pre-commit hooks (required — see Code Style section)
./scripts/setup-pre-commit.sh

# Build the contracts
cargo contract build

# Run tests to ensure everything works
cargo test
```
Expand Down Expand Up @@ -135,29 +127,11 @@ git push origin feature/your-feature-name

## 📝 Code Style Guidelines

See [docs/code-style-guide.md](docs/code-style-guide.md) for the full reference. The highlights are:

### Automated Enforcement

All style checks run automatically via pre-commit hooks (installed by `./scripts/setup-pre-commit.sh`).
You can also run them manually:

```bash
# Format
cargo fmt

# Lint (zero warnings policy)
cargo clippy -- -D warnings

# Run all pre-commit checks
pre-commit run --all-files
```

### Rust Standards
- Follow [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/)
- `rustfmt.toml` enforces formatting — never work around it
- `clippy.toml` enforces lint thresholds — fix warnings, don't silence them with `#[allow]` without a comment justifying why
- Prefer `unwrap()` only inside `#[cfg(test)]` blocks
- Use `cargo fmt` for consistent formatting
- Run `cargo clippy` and fix all warnings
- Prefer `unwrap()` only when you're certain it won't panic

### ink! Smart Contract Best Practices
- Keep contract logic simple and gas-efficient
Expand Down Expand Up @@ -245,53 +219,37 @@ mod tests {
### Before Submitting
- [ ] All tests pass (`cargo test`)
- [ ] Code is formatted (`cargo fmt`)
- [ ] No clippy warnings (`cargo clippy -- -D warnings`)
- [ ] Pre-commit hooks pass (`pre-commit run --all-files`)
- [ ] Documentation updated for any changed behaviour (see [Documentation Guidelines](#-documentation-guidelines))
- [ ] `CHANGELOG.md` updated (if applicable)
- [ ] `cargo audit` passes — no new CVEs (`cargo audit --deny warnings`)
- [ ] `cargo deny check` passes
- [ ] No clippy warnings (`cargo clippy`)
- [ ] Documentation is updated
- [ ] CHANGELOG.md is updated (if applicable)

### PR Description
Your PR should include:
- **Title**: Clear and descriptive (Conventional Commits format: `feat:`, `fix:`, `docs:`, etc.)
- **Title**: Clear and descriptive
- **Description**: What changes were made and why
- **Testing**: How you tested the changes
- **Screenshots**: If UI changes are involved
- **Breaking Changes**: Clearly highlight any breaking changes
- **Documentation**: Links to updated docs

### Review Process
1. **Automated Checks**: CI pipeline runs tests, linting, security scan, and cargo-audit
2. **Peer Review**: At least one maintainer must review and approve
3. **Security Review**: Add `security-review` label for changes to auth, crypto, or cross-contract calls
4. **Approval**: Merge after all checks pass and approval is given
1. **Automated Checks**: CI/CD pipeline runs tests and linting
2. **Peer Review**: At least one maintainer must review
3. **Security Review**: For sensitive changes
4. **Approval**: Merge after all requirements are met

## 🔒 Security Considerations

- Never commit private keys or sensitive data
- Follow secure coding practices for smart contracts — see [SECURITY.md](SECURITY.md)
- Follow secure coding practices for smart contracts
- Consider gas optimization and DoS protection
- Report security vulnerabilities privately via the process in [SECURITY.md](SECURITY.md)

## 📚 Documentation Guidelines

Documentation must stay in sync with code changes. When you submit a PR:

1. **Update docs**: If you change contract behaviour, update the corresponding file in `docs/`.
2. **New features**: Create or update `docs/` coverage. All public `#[ink(message)]` functions must have rustdoc.
3. **Version the doc**: Bump the `> **Documentation Version**` header in any doc file you edit.
4. **Architecture decisions**: If your change affects system design, add an ADR in `docs/adr/`.
5. **Tutorials**: If you add a major new capability, add a tutorial in `docs/tutorials/`.

See [docs/documentation-maintenance.md](docs/documentation-maintenance.md) for the full process.
- Report security vulnerabilities privately

## 📚 Resources

### Development Tools
- [ink! Documentation](https://use.ink/)
- [Substrate Documentation](https://substrate.io/)
- [Rust Book](https://doc.rust-lang.org/book/)
- [Code Style Guide](docs/code-style-guide.md)

### Community
- [Polkadot Discord](https://discord.gg/polkadot)
Expand Down
87 changes: 20 additions & 67 deletions DEVELOPMENT.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,5 @@
# PropChain Development Environment Setup

> **Documentation Version**: 2.0.0 — Updated March 2026
> Covers all contracts shipped in release v2.x. See [Documentation Maintenance](docs/documentation-maintenance.md) for the versioning policy.

This guide will help you set up a complete development environment for PropChain smart contracts.

## Quick Start
Expand All @@ -25,10 +22,9 @@ docker-compose up -d

## Prerequisites

- **Rust** 1.75+ with stable toolchain (see `rust-toolchain.toml`)
- **cargo-contract** 3.x for ink! smart contract development
- **Rust** 1.70+ with stable toolchain
- **Docker** and Docker Compose
- **Node.js** 18+ (for frontend / SDK development)
- **Node.js** 16+ (for frontend development)
- **Git**

## Manual Setup
Expand All @@ -40,17 +36,11 @@ docker-compose up -d
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# The repo's rust-toolchain.toml pins the exact stable channel automatically;
# just run any cargo command and rustup will download the right toolchain.

# Install cargo-contract (ink! CLI)
cargo install cargo-contract --locked --version "^3"
# Install cargo-contract
cargo install cargo-contract --locked

# Add WASM compile target
# Add WASM target
rustup target add wasm32-unknown-unknown

# Optional but recommended
cargo install cargo-deny cargo-audit
```

### 2. Setup Pre-commit Hooks
Expand Down Expand Up @@ -130,46 +120,21 @@ pre-commit run --all-files

```
PropChain-contract/
├── contracts/ # Smart contract source code
│ ├── ai-valuation/ # On-chain AI property valuation oracle
│ ├── analytics/ # Event analytics aggregator
│ ├── bridge/ # Cross-chain asset bridge
│ ├── compliance_registry/ # KYC/AML compliance registry
│ ├── escrow/ # Escrow and settlement engine
│ ├── fees/ # Dynamic fee calculation
│ ├── fractional/ # Fractional ownership shares
│ ├── governance/ # DAO governance and voting
│ ├── insurance/ # Property insurance pools
│ ├── ipfs-metadata/ # IPFS metadata pointer contract
│ ├── lib/ # Shared library code & trait implementations
│ ├── oracle/ # Price and property data oracle
│ ├── prediction-market/ # Property price prediction market
│ ├── property-management/ # Property lifecycle management
│ ├── property-token/ # ERC-721 property NFT (PSP34)
│ ├── proxy/ # Upgradeable proxy pattern
│ ├── staking/ # PROP token staking
│ ├── traits/ # Shared ink! trait interfaces
│ └── zk-compliance/ # Zero-knowledge compliance proofs
├── scripts/ # Development and deployment scripts
├── tests/ # Integration and E2E tests
├── docs/ # Documentation (see docs/documentation-maintenance.md)
│ ├── adr/ # Architecture Decision Records
│ ├── tutorials/ # Step-by-step guides
│ ├── architecture.md
│ ├── code-style-guide.md # Code style reference
│ ├── contracts.md
│ ├── deployment.md
│ ├── incident-response.md # Security incident procedures
│ ├── integration.md
│ ├── security_pipeline.md
│ ├── testing-guide.md
│ └── threat-model.md # Threat model & mitigations
├── security-audit/ # Custom security scanner binary
├── .pre-commit-config.yaml # Pre-commit hook configuration
├── clippy.toml # Clippy lint configuration
├── docker-compose.yml # Local development stack
├── rust-toolchain.toml # Rust version pin
└── rustfmt.toml # Formatting configuration
├── contracts/ # Smart contract source code
│ ├── lib/ # Main contract implementations
│ ├── traits/ # Shared trait definitions
│ └── tests/ # Contract-specific tests
├── scripts/ # Development and deployment scripts
├── tests/ # Integration and E2E tests
├── docs/ # Documentation
│ ├── tutorials/ # Step-by-step guides
│ ├── contracts.md # API documentation
│ ├── integration.md # Integration guide
│ ├── deployment.md # Deployment guide
│ └── architecture.md # Technical architecture
├── .github/workflows/ # CI/CD pipelines
├── docker-compose.yml # Local development stack
└── rust-toolchain.toml # Rust version configuration
```

## Environment Configuration
Expand Down Expand Up @@ -283,15 +248,3 @@ Install these extensions:
2. Follow the [Basic Property Registration Tutorial](docs/tutorials/basic-property-registration.md)
3. Explore the [Contract API](docs/contracts.md)
4. Set up your [Frontend Integration](docs/integration.md)
5. Read the [Code Style Guide](docs/code-style-guide.md)
6. Review the [Security Pipeline](docs/security_pipeline.md)

## Documentation Maintenance

Documentation is versioned alongside the code. When you add or change behaviour:

1. Update the relevant `docs/` file in the same PR.
2. Bump the `> **Documentation Version**` header in any file you change.
3. Add an entry to `docs/adr/` if you are making an architectural decision.

See [docs/documentation-maintenance.md](docs/documentation-maintenance.md) for the full process.
Loading
Loading