Skip to content

Add stamp pool feature for low-latency stamp provisioning (Issue #63)#64

Merged
crtahlin merged 1 commit into
devfrom
feature/stamp-pool-63
Jan 21, 2026
Merged

Add stamp pool feature for low-latency stamp provisioning (Issue #63)#64
crtahlin merged 1 commit into
devfrom
feature/stamp-pool-63

Conversation

@crtahlin
Copy link
Copy Markdown

Summary

  • Implements the Stamp Pool feature for low-latency stamp provisioning
  • Maintains a reserve of pre-purchased postage stamps that can be released immediately (<5 seconds) instead of waiting for blockchain confirmation time (>1 minute)
  • Background task monitors pool levels, syncs from Bee node, and replenishes as needed

Key Components

  • StampPoolManager (app/services/stamp_pool.py): Core service managing the pool, background task, and Bee node integration
  • Pool API endpoints (app/api/endpoints/pool.py):
    • GET /api/v1/pool/status - Get pool status and reserve levels
    • POST /api/v1/pool/acquire - Acquire stamp from pool instantly
    • GET /api/v1/pool/available - List available stamps
    • POST /api/v1/pool/check - Trigger manual maintenance
  • Configuration: 9 new STAMP_POOL_* environment variables
  • Documentation: docs/stamp-pool-guide.md

Configuration

STAMP_POOL_ENABLED=false  # Master switch
STAMP_POOL_RESERVE_SMALL=1   # Depth 17 stamps
STAMP_POOL_RESERVE_MEDIUM=1  # Depth 20 stamps  
STAMP_POOL_RESERVE_LARGE=0   # Depth 22 stamps

Test plan

  • Unit tests for StampPoolManager (26 tests passing)
  • API endpoint tests (status, acquire, available, check)
  • Pool disabled state tests (503 responses)
  • Low reserve warning logic tests

Closes #63

This feature maintains a reserve of pre-purchased postage stamps that can be
released to clients immediately (<5 seconds) without waiting for blockchain
confirmation time (>1 minute).

Key components:
- StampPoolManager service with background task for pool maintenance
- Pool API endpoints: status, acquire, available, check
- Configuration via STAMP_POOL_* environment variables
- Default reserve: 1 small (depth 17), 1 medium (depth 20), 0 large (depth 22)
- Automatic fallback to larger stamps when exact size unavailable
- TTL monitoring and auto-topup for reserve stamps

Closes #63
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Stamp Pool Management for Low-Latency Provisioning

1 participant