soul

package
v0.4.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 18, 2026 License: AGPL-3.0 Imports: 18 Imported by: 0

Documentation

Index

Constants

View Source
const SoulAvatarRendererABI = `` /* 278-byte string literal not displayed */

SoulAvatarRendererABI is the minimal ABI required for public avatar rendering helpers.

View Source
const SoulRegistryABI = `` /* 2513-byte string literal not displayed */

SoulRegistryABI is the minimal ABI required for registry operations performed by the control plane.

Variables

View Source
var ErrPrincipalBindingMissing = errors.New("verified principal binding is missing")

Functions

func DecodeAgentNoncesResult

func DecodeAgentNoncesResult(ret []byte) (*big.Int, error)

DecodeAgentNoncesResult decodes the ABI result for SoulRegistry.agentNonces(agentId).

func DecodeGetAgentWalletResult

func DecodeGetAgentWalletResult(ret []byte) (common.Address, error)

DecodeGetAgentWalletResult decodes the ABI result for SoulRegistry.getAgentWallet(agentId).

func DecodeLastTransferredAtResult

func DecodeLastTransferredAtResult(ret []byte) (*big.Int, error)

DecodeLastTransferredAtResult decodes the ABI result for SoulRegistry.lastTransferredAt(tokenId).

func DecodeMintFeeResult

func DecodeMintFeeResult(ret []byte) (*big.Int, error)

DecodeMintFeeResult decodes the ABI result for SoulRegistry.mintFee().

func DecodeMintSignerResult

func DecodeMintSignerResult(ret []byte) (common.Address, error)

DecodeMintSignerResult decodes the ABI result for SoulRegistry.mintSigner().

func DecodePrincipalOfResult

func DecodePrincipalOfResult(ret []byte) (common.Address, error)

DecodePrincipalOfResult decodes the ABI result for SoulRegistry.principalOf(agentId).

func DecodeRendererRenderAvatarResult added in v0.2.3

func DecodeRendererRenderAvatarResult(ret []byte) (string, error)

DecodeRendererRenderAvatarResult decodes the ABI result for ISoulAvatarRenderer.renderAvatar(tokenId).

func DecodeRendererStyleNameResult added in v0.2.3

func DecodeRendererStyleNameResult(ret []byte) (string, error)

DecodeRendererStyleNameResult decodes the ABI result for ISoulAvatarRenderer.styleName().

func DecodeTokenURIResult added in v0.2.3

func DecodeTokenURIResult(ret []byte) (string, error)

DecodeTokenURIResult decodes the ABI result for SoulRegistry.tokenURI(tokenId).

func DecodeTransferCountResult

func DecodeTransferCountResult(ret []byte) (*big.Int, error)

DecodeTransferCountResult decodes the ABI result for SoulRegistry.transferCount(tokenId).

func DeriveAgentIDHex

func DeriveAgentIDHex(normalizedDomain string, normalizedLocalAgentID string) (string, error)

DeriveAgentIDHex derives the deterministic soul agent id per `docs/adr/0002-canonical-identifiers-and-signatures.md`: uint256(keccak256(utf8("${normalizedDomain}/${normalizedLocalAgentId}"))).

func EncodeAgentNoncesCall

func EncodeAgentNoncesCall(agentID *big.Int) ([]byte, error)

EncodeAgentNoncesCall returns ABI-encoded call data for SoulRegistry.agentNonces(agentId).

func EncodeBurnSoulCall

func EncodeBurnSoulCall(agentID *big.Int) ([]byte, error)

EncodeBurnSoulCall returns ABI-encoded call data for SoulRegistry.burnSoul(agentId).

func EncodeGetAgentWalletCall

func EncodeGetAgentWalletCall(agentID *big.Int) ([]byte, error)

EncodeGetAgentWalletCall returns ABI-encoded call data for SoulRegistry.getAgentWallet(agentId).

func EncodeLastTransferredAtCall

func EncodeLastTransferredAtCall(agentID *big.Int) ([]byte, error)

EncodeLastTransferredAtCall returns ABI-encoded call data for SoulRegistry.lastTransferredAt(tokenId).

func EncodeMintFeeCall

func EncodeMintFeeCall() ([]byte, error)

EncodeMintFeeCall returns ABI-encoded call data for SoulRegistry.mintFee().

func EncodeMintSignerCall

func EncodeMintSignerCall() ([]byte, error)

EncodeMintSignerCall returns ABI-encoded call data for SoulRegistry.mintSigner().

func EncodeMintSoulCall

func EncodeMintSoulCall(to common.Address, agentID *big.Int, metaURI string, avatarStyle uint8, deadline *big.Int, permit []byte) ([]byte, error)

EncodeMintSoulCall returns ABI-encoded call data for SoulRegistry.mintSoul(to, agentId, metaURI, avatarStyle, deadline, permit).

func EncodeMintSoulOwnerCall

func EncodeMintSoulOwnerCall(to common.Address, agentID *big.Int, metaURI string, avatarStyle uint8) ([]byte, error)

EncodeMintSoulOwnerCall returns ABI-encoded call data for SoulRegistry.mintSoulOwner(to, agentId, metaURI, avatarStyle).

func EncodePrincipalOfCall

func EncodePrincipalOfCall(agentID *big.Int) ([]byte, error)

EncodePrincipalOfCall returns ABI-encoded call data for SoulRegistry.principalOf(agentId).

func EncodeRendererRenderAvatarCall added in v0.2.3

func EncodeRendererRenderAvatarCall(tokenID *big.Int) ([]byte, error)

EncodeRendererRenderAvatarCall returns ABI-encoded call data for ISoulAvatarRenderer.renderAvatar(tokenId).

func EncodeRendererStyleNameCall added in v0.2.3

func EncodeRendererStyleNameCall() ([]byte, error)

EncodeRendererStyleNameCall returns ABI-encoded call data for ISoulAvatarRenderer.styleName().

func EncodeRotateWalletCall

func EncodeRotateWalletCall(agentID *big.Int, newWallet common.Address, nonce *big.Int, deadline *big.Int, currentSig []byte, newSig []byte) ([]byte, error)

EncodeRotateWalletCall returns ABI-encoded call data for SoulRegistry.rotateWallet(...).

func EncodeSelfMintSoulCall

func EncodeSelfMintSoulCall(to common.Address, agentID *big.Int, metaURI string, avatarStyle uint8, principal common.Address, deadline *big.Int, attestationSig []byte) ([]byte, error)

EncodeSelfMintSoulCall returns ABI-encoded call data for SoulRegistry.selfMintSoul(to, agentId, metaURI, avatarStyle, principal, deadline, attestationSig).

func EncodeTokenURICall added in v0.2.3

func EncodeTokenURICall(tokenID *big.Int) ([]byte, error)

EncodeTokenURICall returns ABI-encoded call data for SoulRegistry.tokenURI(tokenId).

func EncodeTransferCountCall

func EncodeTransferCountCall(agentID *big.Int) ([]byte, error)

EncodeTransferCountCall returns ABI-encoded call data for SoulRegistry.transferCount(tokenId).

func NormalizeLocalAgentID

func NormalizeLocalAgentID(raw string) (string, error)

NormalizeLocalAgentID normalizes and validates a lesser-soul local agent id.

Rules are locked by `docs/adr/0002-canonical-identifiers-and-signatures.md`.

func SignMintPermit

func SignMintPermit(
	privateKeyHex string,
	chainID int64,
	contractAddress common.Address,
	to common.Address,
	agentID *big.Int,
	metaURI string,
	avatarStyle uint8,
	deadline *big.Int,
) ([]byte, error)

SignMintPermit produces an EIP-712 signature for the MintPermit typed data. The returned bytes are a 65-byte signature with v = 27 or 28.

func SignSelfMintAttestation

func SignSelfMintAttestation(
	privateKeyHex string,
	chainID int64,
	contractAddress common.Address,
	to common.Address,
	agentID *big.Int,
	metaURI string,
	avatarStyle uint8,
	principal common.Address,
	deadline *big.Int,
	submitter common.Address,
) ([]byte, error)

SignSelfMintAttestation produces an EIP-712 signature for the SelfMintAttestation typed data. The returned bytes are a 65-byte signature with v = 27 or 28.

This must match contracts/contracts/SoulRegistry.sol: SelfMintAttestation(address to,uint256 agentId,string metaURI,uint8 avatarStyle,address principal,uint256 deadline,address submitter)

Types

type AttestationsV2

type AttestationsV2 struct {
	HostAttestation string `json:"hostAttestation,omitempty"`
	SelfAttestation string `json:"selfAttestation"`
}

func (*AttestationsV2) Validate

func (a *AttestationsV2) Validate() error

type BoundaryV2

type BoundaryV2 struct {
	ID             string  `json:"id"`
	Category       string  `json:"category"`
	Statement      string  `json:"statement"`
	Rationale      string  `json:"rationale,omitempty"`
	AddedAt        string  `json:"addedAt"`
	AddedInVersion string  `json:"addedInVersion"`
	Supersedes     *string `json:"supersedes,omitempty"`
	Signature      string  `json:"signature"`
}

func (*BoundaryV2) Validate

func (b *BoundaryV2) Validate() error

type CapabilityV2

type CapabilityV2 struct {
	Capability    string         `json:"capability"`
	Scope         string         `json:"scope"`
	Constraints   map[string]any `json:"constraints,omitempty"`
	ClaimLevel    string         `json:"claimLevel"`
	LastValidated string         `json:"lastValidated,omitempty"`
	ValidationRef string         `json:"validationRef,omitempty"`
	DegradesTo    string         `json:"degradesTo,omitempty"`
}

func (*CapabilityV2) Validate

func (c *CapabilityV2) Validate() error

type ChannelsV3

type ChannelsV3 struct {
	ENS   *ENSChannelV3   `json:"ens,omitempty"`
	Email *EmailChannelV3 `json:"email,omitempty"`
	Phone *PhoneChannelV3 `json:"phone,omitempty"`
}

func (*ChannelsV3) Validate

func (c *ChannelsV3) Validate() error

type ContactAvailabilityV3

type ContactAvailabilityV3 struct {
	Schedule string                        `json:"schedule"`
	Timezone string                        `json:"timezone,omitempty"`
	Windows  []ContactAvailabilityWindowV3 `json:"windows,omitempty"`
}

func (*ContactAvailabilityV3) Validate

func (a *ContactAvailabilityV3) Validate() error

type ContactAvailabilityWindowV3

type ContactAvailabilityWindowV3 struct {
	Days      []string `json:"days"`
	StartTime string   `json:"startTime"`
	EndTime   string   `json:"endTime"`
}

func (*ContactAvailabilityWindowV3) Validate

func (w *ContactAvailabilityWindowV3) Validate() error

type ContactFirstContactV3

type ContactFirstContactV3 struct {
	RequireSoul          bool     `json:"requireSoul,omitempty"`
	RequireReputation    *float64 `json:"requireReputation,omitempty"`
	IntroductionExpected bool     `json:"introductionExpected,omitempty"`
}

func (*ContactFirstContactV3) Validate

func (f *ContactFirstContactV3) Validate() error

type ContactPreferencesV3

type ContactPreferencesV3 struct {
	Preferred           string                 `json:"preferred"`
	Fallback            string                 `json:"fallback,omitempty"`
	Availability        ContactAvailabilityV3  `json:"availability"`
	ResponseExpectation ResponseExpectationV3  `json:"responseExpectation"`
	RateLimits          map[string]any         `json:"rateLimits,omitempty"`
	Languages           []string               `json:"languages"`
	ContentTypes        []string               `json:"contentTypes,omitempty"`
	FirstContact        *ContactFirstContactV3 `json:"firstContact,omitempty"`
}

func (*ContactPreferencesV3) Validate

func (p *ContactPreferencesV3) Validate() error

type ContinuityEntryV2

type ContinuityEntryV2 struct {
	Type       string   `json:"type"`
	Timestamp  string   `json:"timestamp"`
	Summary    string   `json:"summary"`
	Recovery   string   `json:"recovery,omitempty"`
	References []string `json:"references,omitempty"`
	Signature  string   `json:"signature"`
}

type ENSChannelV3

type ENSChannelV3 struct {
	Name            string `json:"name"`
	ResolverAddress string `json:"resolverAddress,omitempty"`
	Chain           string `json:"chain,omitempty"`
}

func (*ENSChannelV3) Validate

func (c *ENSChannelV3) Validate() error

type EmailChannelV3

type EmailChannelV3 struct {
	Address      string   `json:"address"`
	Capabilities []string `json:"capabilities"`
	Protocols    []string `json:"protocols,omitempty"`
	Verified     bool     `json:"verified"`
	VerifiedAt   string   `json:"verifiedAt,omitempty"`
}

func (*EmailChannelV3) Validate

func (c *EmailChannelV3) Validate() error

type EndpointsV2

type EndpointsV2 struct {
	ActivityPub string `json:"activitypub,omitempty"`
	MCP         string `json:"mcp,omitempty"`
	Soul        string `json:"soul,omitempty"`
}

func (*EndpointsV2) Validate

func (e *EndpointsV2) Validate() error

type LifecycleV2

type LifecycleV2 struct {
	Status           string  `json:"status"`
	StatusChangedAt  string  `json:"statusChangedAt"`
	Reason           *string `json:"reason,omitempty"`
	SuccessorAgentID *string `json:"successorAgentId,omitempty"`
}

func (*LifecycleV2) Validate

func (l *LifecycleV2) Validate() error

type PhoneChannelV3

type PhoneChannelV3 struct {
	Number       string   `json:"number"`
	Capabilities []string `json:"capabilities"`
	Provider     string   `json:"provider,omitempty"`
	Verified     bool     `json:"verified"`
	VerifiedAt   string   `json:"verifiedAt,omitempty"`
}

func (*PhoneChannelV3) Validate

func (c *PhoneChannelV3) Validate() error

type PrincipalDeclarationBindingV2 added in v0.4.0

type PrincipalDeclarationBindingV2 struct {
	Identifier  string
	Declaration string
	Signature   string
	DeclaredAt  string
}

PrincipalDeclarationBindingV2 carries the host-verified principal fields that were accepted during the registration proof flow. The registration file leaf validator remains compatible with the v2 public schema, while host publication uses this binding to prevent a valid principal declaration from being replayed into another agent's registration.

type PrincipalDeclarationV2

type PrincipalDeclarationV2 struct {
	Type        string `json:"type"`
	Identifier  string `json:"identifier"`
	DisplayName string `json:"displayName,omitempty"`
	ContactURI  string `json:"contactUri,omitempty"`
	Declaration string `json:"declaration"`
	Signature   string `json:"signature"`
	DeclaredAt  string `json:"declaredAt"`
}

func (*PrincipalDeclarationV2) Validate

func (p *PrincipalDeclarationV2) Validate() error

func (*PrincipalDeclarationV2) ValidateVerifiedBinding added in v0.4.0

func (p *PrincipalDeclarationV2) ValidateVerifiedBinding(binding PrincipalDeclarationBindingV2) error

type RegistrationFileV2

type RegistrationFileV2 struct {
	Version   string                 `json:"version"`
	AgentID   string                 `json:"agentId"`
	Domain    string                 `json:"domain"`
	LocalID   string                 `json:"localId"`
	Wallet    string                 `json:"wallet"`
	Principal PrincipalDeclarationV2 `json:"principal"`

	SelfDescription SelfDescriptionV2   `json:"selfDescription"`
	Capabilities    []CapabilityV2      `json:"capabilities"`
	Boundaries      []BoundaryV2        `json:"boundaries"`
	Transparency    map[string]any      `json:"transparency"`
	Continuity      []ContinuityEntryV2 `json:"continuity,omitempty"`
	Endpoints       EndpointsV2         `json:"endpoints"`
	Lifecycle       LifecycleV2         `json:"lifecycle"`

	PreviousVersionURI *string `json:"previousVersionUri,omitempty"`
	ChangeSummary      *string `json:"changeSummary,omitempty"`

	Attestations AttestationsV2 `json:"attestations"`
	Created      string         `json:"created"`
	Updated      string         `json:"updated"`
}

RegistrationFileV2 is the v2 Soul Registration File schema (lesser-soul/SPEC.md Appendix A).

func ParseRegistrationFileV2

func ParseRegistrationFileV2(body []byte) (*RegistrationFileV2, error)

func (*RegistrationFileV2) Validate

func (r *RegistrationFileV2) Validate() error

type RegistrationFileV3

type RegistrationFileV3 struct {
	Version   string                 `json:"version"`
	AgentID   string                 `json:"agentId"`
	Domain    string                 `json:"domain"`
	LocalID   string                 `json:"localId"`
	Wallet    string                 `json:"wallet"`
	Principal PrincipalDeclarationV2 `json:"principal"`

	SelfDescription SelfDescriptionV2   `json:"selfDescription"`
	Capabilities    []CapabilityV2      `json:"capabilities"`
	Boundaries      []BoundaryV2        `json:"boundaries"`
	Transparency    map[string]any      `json:"transparency"`
	Continuity      []ContinuityEntryV2 `json:"continuity,omitempty"`
	Endpoints       EndpointsV2         `json:"endpoints"`
	Lifecycle       LifecycleV2         `json:"lifecycle"`

	Channels           *ChannelsV3           `json:"channels,omitempty"`
	ContactPreferences *ContactPreferencesV3 `json:"contactPreferences,omitempty"`

	PreviousVersionURI *string `json:"previousVersionUri,omitempty"`
	ChangeSummary      *string `json:"changeSummary,omitempty"`

	Attestations AttestationsV2 `json:"attestations"`
	Created      string         `json:"created"`
	Updated      string         `json:"updated"`
}

RegistrationFileV3 is the v3 Soul Registration File schema (lesser-soul/SPEC-v3-draft.md Appendix F). v3 is strictly additive over v2.

func ParseRegistrationFileV3

func ParseRegistrationFileV3(body []byte) (*RegistrationFileV3, error)

func (*RegistrationFileV3) Validate

func (r *RegistrationFileV3) Validate() error

type ResponseExpectationV3

type ResponseExpectationV3 struct {
	Target    string `json:"target"`
	Guarantee string `json:"guarantee"`
}

func (*ResponseExpectationV3) Validate

func (r *ResponseExpectationV3) Validate() error

type SelfDescriptionV2

type SelfDescriptionV2 struct {
	Purpose      string `json:"purpose"`
	Constraints  string `json:"constraints,omitempty"`
	Commitments  string `json:"commitments,omitempty"`
	Limitations  string `json:"limitations,omitempty"`
	AuthoredBy   string `json:"authoredBy"`
	MintingModel string `json:"mintingModel,omitempty"`
}

func (*SelfDescriptionV2) Validate

func (s *SelfDescriptionV2) Validate() error

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL