openyield/x/guild/keeper/msg_server.go

package keeper

// msg_server.go implements the guild module's MsgServer (P3, REQ-051,
// REQ-053, REQ-057, REQ-058, REQ-061). The MsgServer wraps the Keeper + the
// StandKeeper + StashKeeper expected-keeper shims (already on the Keeper).
//
// Each method returns a (*Response, error). Handler state-machine ordering
// is enforced: ValidateBasic -> handler authz/gate -> state mutation ->
// ctx.EventManager().EmitEvent.
//
// Handler set:
//   - CreateGuild (REQ-051): validate, idempotency, persist Guild with
//     CommonBondHash + PublicProfile, surface a jurisdictional disclaimer
//     (REQ-061).
//   - CreateChapter (REQ-053): validate, idempotency, load Parent Guild,
//     pin SecessionTermsHash, set IsChapter=true + ParentGuildID, record
//     GoodStandingLiens (SecuredAtFounding=true), reject cooling below the
//     protocol minimum, persist, surface a disclaimer (REQ-061).
//   - OneTapExitStand (REQ-057): validate, assert Stand type is Household
//     via StandKeeper shim (nil REJECTS), dissolve the Stand + return assets
//     to the Holder's Stash via StashKeeper shim (nil skips the return,
//     still emits the dissolution event), emit event.
//   - DelegateConfederationVoice (REQ-058): validate, assert Confederation
//     Stand type via StandKeeper shim, record one delegation per member
//     Stand (duplicate REJECTED), emit event.
//   - AddLien (REQ-053): validate, load Guild, REJECT any new
//     SecuredAtFounding=true lien (founding is one-time — REQ-053/REQ-081),
//     persist the lien, emit event.
//
// Nil-shim behavior (simtest wiring): a nil StandKeeper REJECTS the
// OneTapExitStand + DelegateConfederationVoice handlers (the Household /
// Confederation type check is load-bearing — it cannot be skipped). A nil
// StashKeeper skips the asset return on one-tap exit (the handler still
// emits the dissolution event — the asset return is a side-effect the
// simtest stub records).

import (
	"fmt"

	sdk "github.com/cosmos/cosmos-sdk/types"

	"github.com/oy/openyield/x/guild/types"
)

// DisclaimerJurisdictional is the jurisdictional disclaimer surfaced at
// every charter signing (REQ-061). NOT session-bounded — surfaced at every
// CreateGuild + CreateChapter. The disclaimer is a fixed string (the live
// jurisdictional overlay lands in a later phase; the simtest asserts the
// Disclaimer field is non-empty).
const DisclaimerJurisdictional = "OpenYield Guilds are self-governed mesh collectives; the protocol does not provide legal, tax, or fiduciary advice. Signers affirm they have reviewed the Common Bond + jurisdictional obligations before signing."

// msgServer is the concrete MsgServer implementation wrapping the Keeper.
type msgServer struct {
	Keeper
}

// NewMsgServerImpl returns the guild MsgServer for the provided Keeper.
func NewMsgServerImpl(k Keeper) types.MsgServer {
	return &msgServer{Keeper: k}
}

var _ types.MsgServer = msgServer{}

// unwrapCtx extracts the sdk.Context from the interface-typed ctx.
func unwrapCtx(ctx interface{}) sdk.Context {
	if c, ok := ctx.(sdk.Context); ok {
		return c
	}
	panic(fmt.Sprintf("guild: expected sdk.Context, got %T", ctx))
}

// --- CreateGuild (REQ-051, REQ-061) -------------------------------------------

// CreateGuild creates a Guild with a Common Bond hash + Public Profile
// (REQ-051). The handler enforces:
//  1. ValidateBasic (stateless — non-empty fields + non-empty
//     CommonBondHash).
//  2. Idempotency: guild-id must not already exist.
//  3. Persist the Guild with CommonBondHash + PublicProfile (the Common
//     Bond is hash-pinned at creation — immutable; the handler does NOT
//     store the bond text, only the hash).
//  4. Surface a jurisdictional disclaimer (REQ-061) in the response.
//
// On success the Guild is persisted and an event is emitted.
func (s msgServer) CreateGuild(ctx interface{}, msg *types.MsgCreateGuild) (*types.MsgCreateGuildResponse, error) {
	if err := msg.ValidateBasic(); err != nil {
		return nil, err
	}
	sdkCtx := unwrapCtx(ctx)

	// Idempotency: guild-id must not already exist.
	if _, ok := s.Keeper.GetGuild(sdkCtx, msg.GuildID); ok {
		return nil, fmt.Errorf("guild: guild %q already exists", msg.GuildID)
	}

	g := types.Guild{
		GuildID:            msg.GuildID,
		Name:               msg.Name,
		FounderReach:       msg.FounderReach,
		CreatedAt:          sdkCtx.BlockTime().Unix(),
		StandAffiliationID: msg.StandAffiliationID,
		CommonBondHash:     msg.CommonBondHash,
		PublicProfile:      msg.PublicProfile,
		IsChapter:          false,
		ParentGuildID:      "",
	}
	s.Keeper.SetGuild(sdkCtx, g)

	sdkCtx.EventManager().EmitEvent(sdk.NewEvent(
		"guild.guild_created",
		sdk.NewAttribute("guild_id", msg.GuildID),
		sdk.NewAttribute("founder_reach", msg.FounderReach),
	))
	return &types.MsgCreateGuildResponse{Disclaimer: DisclaimerJurisdictional}, nil
}

// --- CreateChapter (REQ-053, REQ-061) -----------------------------------------

// CreateChapter creates a Chapter under a Parent Guild (REQ-053). The
// handler enforces:
//  1. ValidateBasic (stateless — non-empty fields, SecessionTerms valid +
//     protocol-minimum-bounded, each GoodStandingLien is SecuredAtFounding).
//  2. Idempotency: chapter guild-id must not already exist.
//  3. Load the Parent Guild (must exist; must NOT itself be a Chapter — a
//     Chapter cannot have a Chapter parent).
//  4. Pin the SecessionTerms hash (HashSecessionTerms — immutable; no
//     handler to amend it).
//  5. Set IsChapter=true + ParentGuildID + GoodStandingLiens (each with
//     SecuredAtFounding=true — ValidateBasic already enforced this).
//  6. Persist the Chapter.
//  7. Surface a jurisdictional disclaimer (REQ-061) in the response.
//
// On success the Chapter is persisted and an event is emitted.
func (s msgServer) CreateChapter(ctx interface{}, msg *types.MsgCreateChapter) (*types.MsgCreateChapterResponse, error) {
	if err := msg.ValidateBasic(); err != nil {
		return nil, err
	}
	sdkCtx := unwrapCtx(ctx)

	// Idempotency: chapter guild-id must not already exist.
	if _, ok := s.Keeper.GetGuild(sdkCtx, msg.GuildID); ok {
		return nil, fmt.Errorf("guild: chapter %q already exists", msg.GuildID)
	}

	// Load the Parent Guild (must exist; must NOT itself be a Chapter).
	parent, ok := s.Keeper.GetGuild(sdkCtx, msg.ParentGuildID)
	if !ok {
		return nil, fmt.Errorf("guild: parent guild %q not found (REQ-053)", msg.ParentGuildID)
	}
	if parent.IsChapter {
		return nil, fmt.Errorf("guild: parent %q is itself a Chapter (a Chapter cannot have a Chapter parent — REQ-053)", msg.ParentGuildID)
	}

	// Pin the SecessionTerms hash (immutable — no handler to amend it).
	termsHash := types.HashSecessionTerms(msg.SecessionTerms)

	// GoodStandingLiens are recorded with SecuredAtFounding=true
	// (ValidateBasic already enforced this — founding-locked liens).
	liens := make([]types.Lien, len(msg.GoodStandingLiens))
	copy(liens, msg.GoodStandingLiens)

	chapter := types.Guild{
		GuildID:            msg.GuildID,
		Name:               msg.Name,
		FounderReach:       msg.FounderReach,
		CreatedAt:          sdkCtx.BlockTime().Unix(),
		CommonBondHash:     parent.CommonBondHash, // a Chapter inherits the Parent's Common Bond hash
		PublicProfile:      parent.PublicProfile,  // a Chapter inherits the Parent's Public Profile
		IsChapter:          true,
		ParentGuildID:      msg.ParentGuildID,
		SecessionTermsHash: termsHash,
		GoodStandingLiens:  liens,
	}
	s.Keeper.SetGuild(sdkCtx, chapter)

	sdkCtx.EventManager().EmitEvent(sdk.NewEvent(
		"guild.chapter_created",
		sdk.NewAttribute("guild_id", msg.GuildID),
		sdk.NewAttribute("parent_guild_id", msg.ParentGuildID),
	))
	return &types.MsgCreateChapterResponse{Disclaimer: DisclaimerJurisdictional}, nil
}

// --- OneTapExitStand (REQ-057) ------------------------------------------------

// OneTapExitStand one-tap exits a Household Stand (REQ-057). The handler
// enforces:
//  1. ValidateBasic (stateless).
//  2. StandKeeper shim must be non-nil (the Household type check is
//     load-bearing — a nil shim is a wiring error, REJECTED).
//  3. The Stand must exist + its type must be "Household" (one-tap exit is
//     Household-only — a Crew / Entity / etc. Stand is REJECTED).
//  4. StashKeeper shim: if non-nil, call ReturnAssetsToHolder to return the
//     dissolved Stand's assets to the Holder's Stash (a nil shim skips the
//     return — simtest wiring; the dissolution event is still emitted). A
//     non-nil error from ReturnAssetsToHolder REJECTS the dissolution (the
//     asset return is load-bearing — a failed return leaves the Stand
//     intact).
//  5. Emit the dissolution event.
//
// The signer is treated as the Holder (the Reach the assets are returned
// to). The live authz (signer must be the Stand's admin-reach) is deferred
// (simtest grade).
func (s msgServer) OneTapExitStand(ctx interface{}, msg *types.MsgOneTapExitStand) (*types.MsgOneTapExitStandResponse, error) {
	if err := msg.ValidateBasic(); err != nil {
		return nil, err
	}
	sdkCtx := unwrapCtx(ctx)

	// StandKeeper shim must be non-nil (the type check is load-bearing).
	if s.Keeper.standKeeper == nil {
		return nil, fmt.Errorf("guild: StandKeeper not wired (OneTapExitStand rejected — Household type check is load-bearing)")
	}

	// The Stand must exist + be a Household (one-tap exit is Household-only).
	standType, exists := s.Keeper.standKeeper.GetStand(msg.StandID)
	if !exists {
		return nil, fmt.Errorf("guild: stand %q not found (OneTapExitStand rejected)", msg.StandID)
	}
	if standType != "Household" {
		return nil, fmt.Errorf("guild: stand %q type %q is not a Household (one-tap exit is Household-only — REQ-057)", msg.StandID, standType)
	}

	// StashKeeper: return the dissolved Stand's assets to the Holder's Stash.
	// A nil shim skips the return (simtest wiring); a non-nil error REJECTS
	// (the asset return is load-bearing).
	if s.Keeper.stashKeeper != nil {
		if err := s.Keeper.stashKeeper.ReturnAssetsToHolder(msg.Signer, msg.StandID); err != nil {
			return nil, fmt.Errorf("guild: return assets to holder %q for stand %q: %w", msg.Signer, msg.StandID, err)
		}
	}

	sdkCtx.EventManager().EmitEvent(sdk.NewEvent(
		"guild.one_tap_exit",
		sdk.NewAttribute("stand_id", msg.StandID),
		sdk.NewAttribute("holder_reach", msg.Signer),
	))
	return &types.MsgOneTapExitStandResponse{}, nil
}

// --- DelegateConfederationVoice (REQ-058) -------------------------------------

// DelegateConfederationVoice delegates a member Stand's Voice in a
// Confederation (REQ-058). The handler enforces:
//  1. ValidateBasic (stateless).
//  2. StandKeeper shim must be non-nil (the Confederation type check is
//     load-bearing — a nil shim is a wiring error, REJECTED).
//  3. The Confederation Stand must exist + its type must be "Confederation".
//  4. One delegation per member Stand: a duplicate delegation from the same
//     MemberStandID is REJECTED (one-Stand-one-Vote — each member Stand gets
//     exactly 1 Voice in the Confederation's aggregate, regardless of size).
//  5. Persist the delegation + emit the event.
func (s msgServer) DelegateConfederationVoice(ctx interface{}, msg *types.MsgDelegateConfederationVoice) (*types.MsgDelegateConfederationVoiceResponse, error) {
	if err := msg.ValidateBasic(); err != nil {
		return nil, err
	}
	sdkCtx := unwrapCtx(ctx)

	// StandKeeper shim must be non-nil (the type check is load-bearing).
	if s.Keeper.standKeeper == nil {
		return nil, fmt.Errorf("guild: StandKeeper not wired (DelegateConfederationVoice rejected — Confederation type check is load-bearing)")
	}

	// The Confederation Stand must exist + be a Confederation.
	standType, exists := s.Keeper.standKeeper.GetStand(msg.ConfederationStandID)
	if !exists {
		return nil, fmt.Errorf("guild: confederation stand %q not found", msg.ConfederationStandID)
	}
	if standType != "Confederation" {
		return nil, fmt.Errorf("guild: stand %q type %q is not a Confederation (REQ-058)", msg.ConfederationStandID, standType)
	}

	// One delegation per member Stand: a duplicate is REJECTED.
	if _, ok := s.Keeper.GetDelegation(sdkCtx, msg.ConfederationStandID, msg.MemberStandID); ok {
		return nil, fmt.Errorf("guild: member stand %q already delegates in confederation %q (one-Stand-one-Vote — duplicate REJECTED — REQ-058)", msg.MemberStandID, msg.ConfederationStandID)
	}

	v := types.ConfederationVoice{
		ConfederationStandID: msg.ConfederationStandID,
		MemberStandID:        msg.MemberStandID,
		DelegateReachID:      msg.DelegateReachID,
		DelegatedAt:          sdkCtx.BlockTime().Unix(),
	}
	s.Keeper.SetDelegation(sdkCtx, v)

	sdkCtx.EventManager().EmitEvent(sdk.NewEvent(
		"guild.confederation_voice_delegated",
		sdk.NewAttribute("confederation_stand_id", msg.ConfederationStandID),
		sdk.NewAttribute("member_stand_id", msg.MemberStandID),
		sdk.NewAttribute("delegate_reach_id", msg.DelegateReachID),
	))
	return &types.MsgDelegateConfederationVoiceResponse{}, nil
}

// --- AddLien (REQ-053) --------------------------------------------------------

// AddLien adds a Good-Standing Lien to a Guild (REQ-053). The handler
// enforces:
//  1. ValidateBasic (stateless — non-empty fields, Lien Amount > 0).
//  2. The Guild must exist.
//  3. REJECT any new SecuredAtFounding=true lien (founding is a one-time
//     event — REQ-053/REQ-081; post-founding liens added via AddLien MUST
//     be SecuredAtFounding=false).
//  4. Persist the lien (assigned the next lien-idx) + emit the event.
func (s msgServer) AddLien(ctx interface{}, msg *types.MsgAddLien) (*types.MsgAddLienResponse, error) {
	if err := msg.ValidateBasic(); err != nil {
		return nil, err
	}
	sdkCtx := unwrapCtx(ctx)

	// The Guild must exist.
	if _, ok := s.Keeper.GetGuild(sdkCtx, msg.GuildID); !ok {
		return nil, fmt.Errorf("guild: guild %q not found (AddLien rejected)", msg.GuildID)
	}

	// REJECT any new SecuredAtFounding=true lien (founding is one-time —
	// REQ-053/REQ-081).
	if msg.Lien.SecuredAtFounding {
		return nil, fmt.Errorf("guild: AddLien rejects SecuredAtFounding=true liens (founding is a one-time event — REQ-053/REQ-081; post-founding liens must be SecuredAtFounding=false)")
	}

	idx := s.Keeper.NextLienIdx(sdkCtx, msg.GuildID)
	s.Keeper.SetLien(sdkCtx, msg.GuildID, idx, msg.Lien)

	sdkCtx.EventManager().EmitEvent(sdk.NewEvent(
		"guild.lien_added",
		sdk.NewAttribute("guild_id", msg.GuildID),
		sdk.NewAttribute("lien_idx", fmt.Sprintf("%d", idx)),
		sdk.NewAttribute("creditor_reach_id", msg.Lien.CreditorReachID),
		sdk.NewAttribute("amount", fmt.Sprintf("%d", msg.Lien.Amount)),
	))
	return &types.MsgAddLienResponse{}, nil
}