Polish Python cryptocurrency onboarding, documentation and security defaults

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,33 @@
+name: Bug report
+description: Report a reproducible problem using disposable data.
+title: "[Bug]: "
+body:
+  - type: markdown
+    attributes:
+      value: "For vulnerabilities, follow SECURITY.md. Never include private keys, mnemonics, wallet files, RPC passwords or personal details."
+  - type: input
+    id: environment
+    attributes:
+      label: Environment
+      description: OS, Python version, repository commit and entry point.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to reproduce
+      description: Use a clean checkout and disposable local data.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected and actual behavior
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Sanitized error output
+      description: Remove secrets and personal information before posting.
+      render: text

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: true

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,18 @@
+name: Feature request
+description: Suggest an improvement to the developer experience or implementation.
+title: "[Feature]: "
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem or use case
+      description: What are you trying to accomplish?
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed behavior
+      description: Include alternatives and consensus or compatibility implications, if any.
+    validations:
+      required: true

.github/pull_request_template.md

@@ -0,0 +1,15 @@
+## What changes?
+
+Describe the problem and the resulting behavior. Link the issue if there is one.
+
+## Validation
+
+List the commands run and their results. Explain any checks you could not run.
+
+## Compatibility and security
+
+State whether this changes consensus, networking, wallet files, APIs or dependencies. Explain migration needs and remaining limitations.
+
+- [ ] Used disposable test data and removed all secrets and personal details.
+- [ ] Updated relevant documentation.
+- [ ] Added behavior tests where the change requires them.

.github/workflows/build.yml

@@ -0,0 +1,36 @@
+name: Build Linux CLI executables
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Install core dependencies and packaging tool
+        run: python -m pip install -r requirements-core.txt pyinstaller
+      - name: Build command-line executables
+        run: |
+          python -m PyInstaller --onefile --name salocoind --add-data 'core/wordlist/english.txt:core/wordlist' salocoind.py
+          python -m PyInstaller --onefile --name salocoin-cli salocoin-cli.py
+      - name: Check executable help
+        run: |
+          dist/salocoind --help
+          dist/salocoin-cli --help
+      - uses: actions/upload-artifact@v4
+        with:
+          name: experimental-linux-cli
+          path: |
+            dist/salocoind
+            dist/salocoin-cli
+          if-no-files-found: error

.github/workflows/ci.yml

@@ -1,144 +1,55 @@
-name: SALOCOIN CI
+name: CI
 
 on:
   push:
-    branches: [ main, develop ]
+    branches: [main, develop, docs/discoverability-security]
   pull_request:
-    branches: [ main, develop ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
 
 jobs:
   test:
+    name: Tests (${{ matrix.os }}, Python ${{ matrix.python }})
     runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
     strategy:
-      matrix:
-        os: [ubuntu-latest, windows-latest, macos-latest]
-        python-version: ['3.9', '3.10', '3.11', '3.12']
       fail-fast: false
-
-    steps:
-    - uses: actions/checkout@v4
-
-    - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5
-      with:
-        python-version: ${{ matrix.python-version }}
-
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install -r requirements.txt
-
-    - name: Run linting
-      run: |
-        pip install flake8
-        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
-        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
-
-    - name: Run tests
-      run: |
-        python -m pytest tests/ -v --tb=short
-
-    - name: Run tests with coverage
-      run: |
-        python -m pytest tests/ --cov=. --cov-report=xml --cov-report=term
-
-    - name: Upload coverage to Codecov
-      if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.11'
-      uses: codecov/codecov-action@v4
-      with:
-        file: ./coverage.xml
-        fail_ci_if_error: false
-
-  type-check:
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@v4
-
-    - name: Set up Python
-      uses: actions/setup-python@v5
-      with:
-        python-version: '3.11'
-
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install -r requirements.txt
-        pip install mypy
-
-    - name: Run type checking
-      run: |
-        mypy --ignore-missing-imports --no-error-summary . || true
-
-  security:
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@v4
-
-    - name: Set up Python
-      uses: actions/setup-python@v5
-      with:
-        python-version: '3.11'
-
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install bandit safety
-
-    - name: Run security checks
-      run: |
-        bandit -r . -x ./tests -ll || true
-        safety check || true
-
-  build:
-    runs-on: ubuntu-latest
-    needs: [test]
-    steps:
-    - uses: actions/checkout@v4
-
-    - name: Set up Python
-      uses: actions/setup-python@v5
-      with:
-        python-version: '3.11'
-
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install -r requirements.txt
-        pip install pyinstaller
-
-    - name: Build executable
-      run: |
-        pyinstaller --onefile --name salocoind salocoind.py
-        pyinstaller --onefile --name salocoin-cli salocoin-cli.py
-
-    - name: Upload artifacts
-      uses: actions/upload-artifact@v4
-      with:
-        name: salocoin-linux
-        path: |
-          dist/salocoind
-          dist/salocoin-cli
-
-  release:
-    runs-on: ubuntu-latest
-    needs: [build]
-    if: startsWith(github.ref, 'refs/tags/v')
+      matrix:
+        include:
+          - os: ubuntu-latest
+            python: '3.10'
+          - os: ubuntu-latest
+            python: '3.12'
+          - os: ubuntu-latest
+            python: '3.13'
+          - os: windows-latest
+            python: '3.12'
+          - os: macos-latest
+            python: '3.12'
     steps:
-    - uses: actions/checkout@v4
-
-    - name: Download artifacts
-      uses: actions/download-artifact@v4
-      with:
-        name: salocoin-linux
-        path: dist/
-
-    - name: Create Release
-      uses: softprops/action-gh-release@v1
-      with:
-        files: |
-          dist/salocoind
-          dist/salocoin-cli
-        draft: true
-        prerelease: false
-      env:
-        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+          cache-dependency-path: requirements-core.txt
+      - name: Install core development dependencies
+        run: python -m pip install -r requirements-core.txt
+      - name: Run tests
+        run: python -m pytest -q
+      - name: Run offline walkthrough
+        run: python examples/offline_walkthrough.py
+      - name: Check documentation links
+        run: python scripts/check_docs.py
+      - name: Compile core entry points
+        run: python -m compileall -q core network rpc examples scripts exchange_node.py salocoind.py
+      - name: Check command-line help
+        run: python salocoind.py --help

.gitignore

@@ -124,3 +124,11 @@ website/
 *.zip
 *.tar.gz
 *.rar
+
+# Disposable development data
+development-data/
+.wallet-*
+
+# Regression tests and runnable examples belong in source control.
+!tests/test_*.py
+!scripts/check_docs.py

CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+Changes below are proposed in the current pull request. They are not a tagged release.
+
+## Unreleased
+
+### Developer experience
+
+- Present the project as a Bitcoin-like Python cryptocurrency implementation.
+- Add an offline keys/signatures/wallet/block-template walkthrough.
+- Add installation, troubleshooting, architecture and coin-customization guides.
+- Add a documentation index, issue/PR templates, and cross-platform CI.
+- Focus required CI on core dependencies and reproducible checks; move Linux executable builds to manual dispatch. Earlier nonblocking audit/type-check commands are not presented as passing quality gates.
+
+### Security behavior changes
+
+- Disable the former flag-only wallet encryption and password-free unlock behavior.
+- Preserve legacy flagged wallet files by refusing saves through the wallet API.
+- Use owner-only atomic wallet writes on POSIX; keys still remain plaintext.
+- Reject new HD wallets with unsupported extra-passphrase persistence.
+- Reject incomplete/empty RPC credentials and unauthenticated non-loopback RPC.
+- Strictly decode Basic authentication and compare credentials in constant time.
+- Require explicit exchange RPC credentials, bind RPC/REST to loopback and remove password logging.
+- Correct RPC server shutdown to use the matching serving loop.
+
+Existing exchange deployments need a protected proxy or tunnel for remote API access. See [security limitations](SECURITY.md) before upgrading. No consensus parameters or historical attribution are changed.

CONTRIBUTING.md

@@ -0,0 +1,28 @@
+# Contributing
+
+Use a branch and propose a pull request with a concrete problem, change and test result. Keep patches focused and explain consensus or wallet-file compatibility changes explicitly.
+
+```sh
+python -m pip install -r requirements-core.txt
+python -m pytest -q
+python examples/offline_walkthrough.py
+python scripts/check_docs.py
+python -m compileall -q core network rpc examples scripts exchange_node.py salocoind.py
+```
+
+Use temporary data directories and disposable keys. Never include mnemonics, private keys, wallet backups, RPC passwords, personal contact details, or production data in tests, logs or issues. Pseudonymous contributions are welcome; do not fabricate commits or change historical attribution.
+
+Add behavior tests for security fixes and consensus changes. Document remaining limits. Do not advertise audits, production readiness, network availability or interoperability without reproducible evidence. For sensitive reports, see [SECURITY.md](SECURITY.md).
+
+## Review workflow
+
+1. Create a branch from the current main branch.
+2. Reproduce the issue with disposable local data.
+3. Make a focused change and update its guide or example.
+4. Run the checks above and open a pull request using the template.
+
+CI runs the core tests, offline example, link checks and compilation on the configured Linux, Windows and macOS Python matrix. A green check validates those steps; it is not a security audit or proof of network interoperability. Optional GPU/GUI/deployment paths are outside that matrix. Linux CLI packaging is available through the separate manual build workflow; its artifacts are experimental, and there is no automatic release/publishing step.
+
+For documentation-only changes, run the link checker and affected examples. For behavioral changes, add a meaningful regression test under `tests/`; these files are allowed in source control.
+
+Avoid broad formatting changes unrelated to your patch. Maintainers can assess a small, reproducible patch more easily. No signed-commit or real-name identity requirement is imposed by this guide.