feat!: color of money — segregated balances per (account, asset, color)

cmd/ledgerctl/accounts/aggregate.go

@@ -99,6 +99,7 @@ func runAggregateVolumes(cmd *cobra.Command, _ []string) error {
 	{
 		type jsonVolume struct {
 			Asset   string `json:"asset"`
+			Color   string `json:"color"`
 			Input   string `json:"input"`
 			Output  string `json:"output"`
 			Balance string `json:"balance"`
@@ -112,6 +113,7 @@ func runAggregateVolumes(cmd *cobra.Command, _ []string) error {
 			balance := new(big.Int).Sub(input, output)
 			volumes = append(volumes, jsonVolume{
 				Asset:   vol.GetAsset(),
+				Color:   vol.GetColor(),
 				Input:   input.String(),
 				Output:  output.String(),
 				Balance: balance.String(),
@@ -130,7 +132,7 @@ func runAggregateVolumes(cmd *cobra.Command, _ []string) error {
 	}
 
 	tableData := pterm.TableData{
-		{"ASSET", "INPUT", "OUTPUT", "BALANCE"},
+		{"ASSET", "COLOR", "INPUT", "OUTPUT", "BALANCE"},
 	}
 
 	for _, vol := range result.GetVolumes() {
@@ -139,6 +141,7 @@ func runAggregateVolumes(cmd *cobra.Command, _ []string) error {
 		balance := new(big.Int).Sub(input, output)
 		tableData = append(tableData, []string{
 			vol.GetAsset(),
+			vol.GetColor(),
 			input.String(),
 			output.String(),
 			formatBalance(balance),

cmd/ledgerctl/accounts/get.go

@@ -3,7 +3,6 @@ package accounts
 import (
 	"errors"
 	"fmt"
-	"sort"
 
 	"github.com/pterm/pterm"
 	"github.com/spf13/cobra"
@@ -129,27 +128,28 @@ func runGet(cmd *cobra.Command, args []string) error {
 
 	if len(account.GetVolumes()) > 0 {
 		volumesTable := pterm.TableData{
-			{"ASSET", "INPUT", "OUTPUT", "BALANCE"},
+			{"ASSET", "COLOR", "INPUT", "OUTPUT", "BALANCE"},
 		}
 
-		assets := make([]string, 0, len(account.GetVolumes()))
-		for asset := range account.GetVolumes() {
-			assets = append(assets, asset)
-		}
-
-		sort.Strings(assets)
-
-		for _, asset := range assets {
-			vol := account.GetVolumes()[asset]
+		// account.GetVolumes() is already sorted by (asset, color) ascending
+		// server-side, so we just render in-order.
+		for _, entry := range account.GetVolumes() {
+			vol := entry.GetVolumes()
 			balance := vol.GetBalance()
 
 			balanceColor := pterm.Green
 			if balance != "" && balance[0] == '-' {
 				balanceColor = pterm.Red
 			}
 
+			displayColor := entry.GetColor()
+			if displayColor == "" {
+				displayColor = "-"
+			}
+
 			volumesTable = append(volumesTable, []string{
-				asset,
+				entry.GetAsset(),
+				displayColor,
 				vol.GetInput(),
 				vol.GetOutput(),
 				balanceColor(balance),

cmd/ledgerctl/queries/execute.go

@@ -233,10 +233,11 @@ func renderAggregate(cmd *cobra.Command, result *commonpb.AggregateResult) error
 	}
 
 	if len(result.GetVolumes()) > 0 {
-		tableData := pterm.TableData{{"ASSET", "INPUT", "OUTPUT"}}
+		tableData := pterm.TableData{{"ASSET", "COLOR", "INPUT", "OUTPUT"}}
 		for _, v := range result.GetVolumes() {
 			tableData = append(tableData, []string{
 				v.GetAsset(),
+				v.GetColor(),
 				v.GetInput().ToBigInt().String(),
 				v.GetOutput().ToBigInt().String(),
 			})
@@ -249,10 +250,11 @@ func renderAggregate(cmd *cobra.Command, result *commonpb.AggregateResult) error
 		pterm.Println()
 		pterm.Printfln("Group: %s", g.GetPrefix())
 
-		tableData := pterm.TableData{{"ASSET", "INPUT", "OUTPUT"}}
+		tableData := pterm.TableData{{"ASSET", "COLOR", "INPUT", "OUTPUT"}}
 		for _, v := range g.GetVolumes() {
 			tableData = append(tableData, []string{
 				v.GetAsset(),
+				v.GetColor(),
 				v.GetInput().ToBigInt().String(),
 				v.GetOutput().ToBigInt().String(),
 			})

cmd/ledgerctl/transactions/create.go

@@ -75,7 +75,7 @@ func NewCreateCommand() *cobra.Command {
 		Long: `Create a new transaction via gRPC.
 
 Postings can be provided via flag, or use a Numscript file.
-Flag format: --posting "source,destination,amount,asset"
+Flag format: --posting "source,destination,amount,asset[,color]"
 
 Examples:
   ledgerctl transactions create --ledger my-ledger --posting "world,bank,1000,USD"
@@ -88,7 +88,7 @@ Examples:
 	}
 
 	cmd.Flags().String("ledger", "", "Name of the ledger")
-	cmd.Flags().StringArray("posting", nil, "Posting in format: source,destination,amount,asset (can be repeated)")
+	cmd.Flags().StringArray("posting", nil, "Posting in format: source,destination,amount,asset[,color] (can be repeated)")
 	cmd.Flags().String("script", "", "Path to a Numscript file (mutually exclusive with --posting)")
 	cmd.Flags().StringArray("var", nil, "Script variable in format: name=value (can be repeated, only with --script)")
 	cmd.Flags().String("reference", "", "Transaction reference")
@@ -460,17 +460,22 @@ func runCreate(cmd *cobra.Command, _ []string) error {
 		pterm.Println("Postings:")
 
 		postingsTable := pterm.TableData{
-			{"#", "SOURCE", "", "DESTINATION", "AMOUNT", "ASSET"},
+			{"#", "SOURCE", "", "DESTINATION", "AMOUNT", "ASSET", "COLOR"},
 		}
 
 		for i, posting := range tx.GetPostings() {
+			color := posting.GetColor()
+			if color == "" {
+				color = "-"
+			}
 			postingsTable = append(postingsTable, []string{
 				strconv.Itoa(i + 1),
 				posting.GetSource(),
 				"→",
 				posting.GetDestination(),
 				posting.GetAmount().Dec(),
 				posting.GetAsset(),
+				color,
 			})
 		}
 
@@ -512,28 +517,36 @@ func runCreate(cmd *cobra.Command, _ []string) error {
 	return nil
 }
 
-// parsePosting parses a posting from string format "source,destination,amount,asset".
+// parsePosting parses a posting from string format
+//   - "source,destination,amount,asset"            (uncolored, 4 fields)
+//   - "source,destination,amount,asset,color"      (colored,   5 fields)
+//
+// The color field is optional. An empty fifth field is treated as no color.
 func parsePosting(s string) (*commonpb.Posting, error) {
 	parts := strings.Split(s, ",")
-	if len(parts) != 4 {
-		return nil, errors.New("expected format: source,destination,amount,asset")
+	if len(parts) != 4 && len(parts) != 5 {
+		return nil, errors.New("expected format: source,destination,amount,asset[,color]")
 	}
 
 	source := strings.TrimSpace(parts[0])
 	destination := strings.TrimSpace(parts[1])
 	amountStr := strings.TrimSpace(parts[2])
 	asset := strings.TrimSpace(parts[3])
+	color := ""
+	if len(parts) == 5 {
+		color = strings.TrimSpace(parts[4])
+	}
 
 	if source == "" || destination == "" || amountStr == "" || asset == "" {
-		return nil, errors.New("all fields are required")
+		return nil, errors.New("source, destination, amount and asset are required")
 	}
 
 	amount, ok := new(big.Int).SetString(amountStr, 10)
 	if !ok {
 		return nil, fmt.Errorf("invalid amount: %s", amountStr)
 	}
 
-	return commonpb.NewPosting(source, destination, asset, amount), nil
+	return commonpb.NewColoredPosting(source, destination, asset, color, amount), nil
 }
 
 // promptVariable prompts the user for a Numscript variable value based on its type.

cmd/ledgerctl/transactions/display_volumes.go

@@ -9,6 +9,8 @@ import (
 )
 
 // renderPostCommitVolumes displays a PostCommitVolumes table in the CLI output.
+// Volumes are listed per (account, asset, color). The "" color is rendered as
+// "-" so the uncolored bucket stands out in the table.
 func renderPostCommitVolumes(pcv *commonpb.PostCommitVolumes) error {
 	if len(pcv.GetVolumesByAccount()) == 0 {
 		return nil
@@ -18,33 +20,28 @@ func renderPostCommitVolumes(pcv *commonpb.PostCommitVolumes) error {
 	pterm.Println("Post-Commit Volumes:")
 
 	table := pterm.TableData{
-		{"ACCOUNT", "ASSET", "INPUT", "OUTPUT"},
+		{"ACCOUNT", "ASSET", "COLOR", "INPUT", "OUTPUT"},
 	}
 
-	// Sort accounts for stable output
 	accounts := make([]string, 0, len(pcv.GetVolumesByAccount()))
 	for account := range pcv.GetVolumesByAccount() {
 		accounts = append(accounts, account)
 	}
-
 	sort.Strings(accounts)
 
 	for _, account := range accounts {
 		vba := pcv.GetVolumesByAccount()[account]
-
-		// Sort assets for stable output
-		assets := make([]string, 0, len(vba.GetVolumes()))
-		for asset := range vba.GetVolumes() {
-			assets = append(assets, asset)
-		}
-
-		sort.Strings(assets)
-
-		for _, asset := range assets {
-			v := vba.GetVolumes()[asset]
+		// VolumesByAssets.Volumes is sorted by (asset, color) server-side.
+		for _, entry := range vba.GetVolumes() {
+			v := entry.GetVolumes()
+			displayColor := entry.GetColor()
+			if displayColor == "" {
+				displayColor = "-"
+			}
 			table = append(table, []string{
 				account,
-				asset,
+				entry.GetAsset(),
+				displayColor,
 				v.GetInput(),
 				v.GetOutput(),
 			})

cmd/ledgerctl/transactions/get.go

@@ -148,7 +148,7 @@ func runGet(cmd *cobra.Command, args []string) error {
 		pterm.Println("Postings:")
 
 		postingsTable := pterm.TableData{
-			{"#", "SOURCE", "", "DESTINATION", "AMOUNT", "ASSET"},
+			{"#", "SOURCE", "", "DESTINATION", "AMOUNT", "ASSET", "COLOR"},
 		}
 
 		termWidth := pterm.GetTerminalWidth()
@@ -167,7 +167,7 @@ func runGet(cmd *cobra.Command, args []string) error {
 
 			for line := range maxLines {
 				src, dst := "", ""
-				num, arrow, amount, asset := "", "", "", ""
+				num, arrow, amount, asset, color := "", "", "", "", ""
 
 				if line < len(srcLines) {
 					src = srcLines[line]
@@ -188,10 +188,14 @@ func runGet(cmd *cobra.Command, args []string) error {
 					arrow = "→"
 					amount = posting.GetAmount().Dec()
 					asset = posting.GetAsset()
+					color = posting.GetColor()
+					if color == "" {
+						color = "-"
+					}
 				}
 
 				postingsTable = append(postingsTable, []string{
-					num, src, arrow, dst, amount, asset,
+					num, src, arrow, dst, amount, asset, color,
 				})
 			}
 		}

cmd/ledgerctl/transactions/revert.go

@@ -233,17 +233,22 @@ func runRevert(cmd *cobra.Command, args []string) error {
 		pterm.Println("Revert Postings:")
 
 		postingsTable := pterm.TableData{
-			{"#", "SOURCE", "", "DESTINATION", "AMOUNT", "ASSET"},
+			{"#", "SOURCE", "", "DESTINATION", "AMOUNT", "ASSET", "COLOR"},
 		}
 
 		for i, posting := range revertedTx.GetRevertTransaction().GetPostings() {
+			color := posting.GetColor()
+			if color == "" {
+				color = "-"
+			}
 			postingsTable = append(postingsTable, []string{
 				strconv.Itoa(i + 1),
 				posting.GetSource(),
 				"→",
 				posting.GetDestination(),
 				posting.GetAmount().Dec(),
 				posting.GetAsset(),
+				color,
 			})
 		}
 

docs/ops/cli.md

@@ -1341,7 +1341,7 @@ ledgerctl transactions create [flags]
 | Flag | Default | Description |
 |------|---------|-------------|
 | `--ledger` | | Name of the ledger |
-| `--posting` | | Posting in format: `source,destination,amount,asset` (can be repeated) |
+| `--posting` | | Posting in format: `source,destination,amount,asset[,color]` (can be repeated) |
 | `--script` | | Path to a Numscript file (mutually exclusive with `--posting`) |
 | `--var` | | Script variable in format: `name=value` (can be repeated, only with `--script`) |
 | `--reference` | | Transaction reference |
@@ -1372,8 +1372,26 @@ ledgerctl transactions create --ledger my-ledger \
 ledgerctl transactions create --ledger my-ledger \
   --posting "empty-account,destination,1000,USD" \
   --force
+
+# Colored postings (segregated balances per (account, asset, color)).
+# Color must match ^[A-Z]*$. An empty/missing color is the uncolored bucket
+# and is itself segregated from every colored bucket.
+ledgerctl transactions create --ledger my-ledger \
+  --posting "world,treasury,1000,USD/2,GRANTS"
+
+# Mixed colored and uncolored postings in a single transaction
+ledgerctl transactions create --ledger my-ledger \
+  --posting "world,treasury,500,USD/2" \
+  --posting "world,treasury,500,USD/2,OPS"
 ```
 
+**Inspecting colored balances:**
+
+`ledgerctl accounts get` lists one row per `(asset, color)` tuple. To sum
+every colored bucket of the same asset into a single uncolored entry, pass
+`?collapseColors=true` on the HTTP endpoint (the CLI surfaces the raw,
+segregated view by design).
+
 **Creating transactions with Numscript:**
 
 ```bash

docs/technical/architecture/README.md

@@ -36,6 +36,7 @@ Cross-cutting concerns (overall design, data flows shared across subsystems, the
 |----------|-----|
 | [data-flows.md](data-flows.md) | Sequence diagrams that span multiple subsystems. |
 | [data-model.md](data-model.md) | Ledgers, transactions, postings — the core domain shape. |
+| [data-model/color-of-money.md](data-model/color-of-money.md) | Per-bucket "color of money" balance segregation — key encoding, numscript contract, collapse modes. |
 | [audit-vs-technical-state.md](audit-vs-technical-state.md) | Boundary between business truth, governance truth, operational state, and rebuildable projections. |
 | [primitives/uint256-wire-format.md](primitives/uint256-wire-format.md) | Fixed-size monetary-amount wire format used everywhere on the boundary. |