EscrowMint Go

Exact, Redis-backed bounded consumption for shared quotas.

EscrowMint Go is for cases where many threads, processes, or services need to consume from the same global quota without letting it go below zero.

Good fits:

• prepaid credits
• inventory reservation
• budget caps
• worker permit pools
• campaign spend controls

Why EscrowMint

EscrowMint is not a generic counter library. It is a quota and reservation library with application-level semantics:

• consistent pool top-up
• exact bounded decrement
• idempotent consume
• reservation with TTL
• commit and cancel flow
• crash recovery via lazy expiry reclaim

Install

go get github.com/biprakanta/escrowmint-go/escrowmint

Quickstart

package main

import (
	"context"
	"log"

	"github.com/biprakanta/escrowmint-go/escrowmint"
)

func main() {
	ctx := context.Background()

	client, err := escrowmint.NewClient(ctx, escrowmint.Config{
		URL: "redis://localhost:6379/0",
	})
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()

	result, err := client.TryConsume(ctx, "wallet:123", 5, escrowmint.ConsumeOptions{
		IdempotencyKey: "req-001",
	})
	if err != nil {
		log.Fatal(err)
	}

	log.Println(result.Applied, result.Remaining)
}

Top Up Pool

result, err := client.TopUp(ctx, "wallet:123", 25, escrowmint.TopUpOptions{
	IdempotencyKey: "credit-001",
})
if err != nil {
	log.Fatal(err)
}

log.Println(result.Added, result.Available)

Crash-Safe Reservation

reservation, err := client.Reserve(ctx, "wallet:123", 10, 30000, escrowmint.ReserveOptions{})
if err != nil {
	log.Fatal(err)
}

result, err := client.Commit(ctx, "wallet:123", reservation.ReservationID)
if err != nil {
	log.Fatal(err)
}

_ = result

If a worker crashes after Reserve but before Commit, the held quota is released after TTL expiry on the next mutation or GetState call for that same resource.

Current API

client.TryConsume(ctx, resource, amount, opts)
client.TopUp(ctx, resource, amount, opts)
client.Reserve(ctx, resource, amount, ttlMS, opts)
client.Commit(ctx, resource, reservationID)
client.Cancel(ctx, resource, reservationID)
client.GetState(ctx, resource)

Chunk Lease Path

EscrowMint Go also ships an explicit chunk-lease lifecycle for hot resources:

lease, err := client.AllocateChunk(ctx, "wallet:123", 100, escrowmint.AllocateChunkOptions{
	OwnerID: "worker-a",
	TTLMS:   30000,
})
if err != nil {
	log.Fatal(err)
}

result, err := client.ConsumeChunk(ctx, "wallet:123", lease.LeaseID, 5, "worker-a")
if err != nil {
	log.Fatal(err)
}

_, _ = result, lease

This is the authoritative distributed chunk path. It keeps chunk state in Redis and supports expiry reclaim, renew, release, and worker ownership checks.

How It Works

• Redis remains the source of truth for each resource.
• Lua scripts make each operation atomic.
• Reservations move units from available to reserved.
• Top-ups add units back into available without bypassing expiry reclaim.
• Pending reservations are indexed by expiry time in Redis.
• Expired reservations are reclaimed lazily in bounded batches on the next touch of that resource.
• Terminal reservation outcomes are moved into short-lived receipt keys so the hot reservation hash stays small.

Direct Path and Chunk Lease Path

EscrowMint currently ships both models.

The direct path is the shared-resource path:

• TryConsume, Reserve, Commit, and Cancel
• TopUp for consistent replenishment of the shared pool
• exact bounded updates against the resource's shared state
• the simplest way to get correctness and crash recovery

The chunk lease path adds a worker-owned lease layer on top of that model:

• AllocateChunk, ConsumeChunk, RenewChunk, ReleaseChunk, and GetChunk
• explicit escrow or chunk allocation per worker
• better control over hot-resource ownership, refill, expiry, and reclaim
• more operational complexity than the direct path

Choose the direct path when you want the simplest exact path.

Choose the chunk lease path when a resource benefits from explicit worker-level quota management.

The current chunk lease implementation is an authoritative Redis-backed lease lifecycle. It improves the state model for hot resources, but it does not automatically become a no-Redis local fast path. If you want fewer Redis round trips than the shipped chunk API provides, you can layer an in-process chunk consumer on top of the authoritative lease lifecycle.

See docs/CHUNK_LEASES.md.

Development

go test ./...
go test ./... -cover
go mod tidy
gofmt -w ./...

Notes:

• module path is go.mod
• tests use Docker-backed Redis integration cases

Support

• Go module floor: 1.22+
• Tested in CI: 1.25 and 1.26
• Redis: intended for modern Redis deployments that support Lua scripting and standard key expiry semantics
• Stability: the module is published and follows SemVer before 1.0; breaking API changes remain possible, but release notes will call them out explicitly

Release Process

EscrowMint Go uses Conventional Commits and Release Please for semantic versioning and release notes.

• fix: -> patch release
• feat: -> minor release
• feat!: or BREAKING CHANGE: -> major release

When releasable commits land on main, Release Please opens or updates a release PR. Merging that PR updates CHANGELOG.md, creates the vX.Y.Z tag, and creates the GitHub release notes. The existing tag workflow then verifies the tagged release commit.

Docs

• Direct Path API
• Architecture
• Chunk Lease Design
• Lua Script Notes
• Changelog
• Contributing