deploy

package
v0.6.6 Latest Latest
Warning

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

 Go to latest Published: Feb 19, 2026 License: AGPL-3.0 Imports: 29 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	MintStatusMinted         = "MINTED"
	MintStatusAlreadyOwned   = "ALREADY_OWNED"
	MintStatusUpdateRequired = "UPDATE_REQUIRED"
	MintStatusUpdated        = "UPDATED"
)

MintStatus constants

View Source 
const (
	WALStateIdle       = "IDLE"
	WALStateMinting    = "MINTING"
	WALStateConfirming = "CONFIRMING"
)

WAL State constants

View Source 
const DefaultMaxJSONSize = 24 * 1024

DefaultMaxJSONSize is the fallback max size for agent JSON files (24KB) The actual limit is fetched from backend via schema endpoint

View Source 
const (
	// SDKAuthMessagePrefix is the prefix used for signing auth challenges
	SDKAuthMessagePrefix = "Teneo SDK auth: "
)

Variables

View Source 
var ErrGaslessMintingDisabled = fmt.Errorf("gasless minting is temporarily disabled")

ErrGaslessMintingDisabled indicates gasless minting is disabled

View Source 
var ErrSchemaOutdated = fmt.Errorf("schema version outdated")

ErrSchemaOutdated indicates the schema version is outdated

View Source 
var ErrSessionExpired = fmt.Errorf("session expired")

ErrSessionExpired indicates the session token has expired

Functions

func AbandonAgent 

func AbandonAgent(agentID string, config *MintConfig) error

AbandonAgent is a convenience function to abandon a reservation

func GenerateConfigHash 

func GenerateConfigHash(config *AgentConfig) string

GenerateConfigHash generates a canonical v4 hash of the agent config. v4 includes ALL command fields (description, argument, parameters, strictArg, minArgs, maxArgs, priceType, taskUnit, timeUnit) and capability descriptions — so any change to any field triggers an IPFS re-upload. Image is deliberately excluded — image changes are cosmetic, not functional.

Types

type AbandonRequest 

type AbandonRequest struct {
	Wallet    string `json:"wallet"`
	AgentID   string `json:"agent_id"`
	Challenge string `json:"challenge"`
	Signature string `json:"signature"`
}

AbandonRequest is the request body for POST /api/sdk/agent/abandon

type AbandonResponse 

type AbandonResponse struct {
	Success bool   `json:"success"`
	Message string `json:"message"`
	AgentID string `json:"agent_id"`
}

AbandonResponse is the response from POST /api/sdk/agent/abandon

type AgentConfig 

type AgentConfig struct {
	Name            string       `json:"name"`
	AgentID         string       `json:"agentId"`
	Description     string       `json:"description"`
	Image           string       `json:"image,omitempty"`
	AgentType       string       `json:"agentType"`
	Categories      []string     `json:"categories"`
	Capabilities    []Capability `json:"capabilities"`
	Commands        []Command    `json:"commands,omitempty"`
	NlpFallback     bool         `json:"nlpFallback"`
	McpManifest     string       `json:"mcpManifest,omitempty"`
	MetadataVersion string       `json:"metadata_version,omitempty"`
}

AgentConfig represents the agent configuration from JSON file

type Authenticator 

type Authenticator struct {
	// contains filtered or unexported fields
}

Authenticator handles SDK authentication with the backend

func NewAuthenticator 

func NewAuthenticator(privateKeyHex string, client *HTTPClient) (*Authenticator, error)

NewAuthenticator creates a new authenticator

func (*Authenticator) Authenticate 

func (a *Authenticator) Authenticate() (sessionToken string, expiresAt int64, err error)

Authenticate performs the full challenge-response authentication flow

func (*Authenticator) GetAddress 

func (a *Authenticator) GetAddress() string

GetAddress returns the wallet address

func (*Authenticator) SignChallenge 

func (a *Authenticator) SignChallenge(challenge string) (string, error)

SignChallenge signs a challenge with the private key

type Capability 

type Capability struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
}

Capability represents an agent capability

type ChainClient 

type ChainClient struct {
	// contains filtered or unexported fields
}

ChainClient handles on-chain operations

func NewChainClient 

func NewChainClient(rpcEndpoint, contractAddress, chainIDStr, privateKeyHex string) (*ChainClient, error)

NewChainClient creates a new chain client

func (*ChainClient) Close 

func (c *ChainClient) Close()

Close closes the client connection

func (*ChainClient) ExecuteMint 

func (c *ChainClient) ExecuteMint(ctx context.Context, signature string, mintPrice *big.Int) (*MintResult, error)

ExecuteMint executes the on-chain mint transaction

func (*ChainClient) ExtractTokenIDFromReceipt 

func (c *ChainClient) ExtractTokenIDFromReceipt(receipt *types.Receipt) (uint64, error)

ExtractTokenIDFromReceipt extracts the token ID from Minted or Transfer event in the receipt

func (*ChainClient) GetAddress 

func (c *ChainClient) GetAddress() string

GetAddress returns the wallet address

func (*ChainClient) GetMintPrice added in v0.6.0 

func (c *ChainClient) GetMintPrice(ctx context.Context) (*big.Int, error)

GetMintPrice queries the mintPrice from the contract

func (*ChainClient) GetTokenID 

func (c *ChainClient) GetTokenID(ctx context.Context) (uint64, error)

GetTokenID gets the token ID owned by the wallet (if any)

func (*ChainClient) GetTransactionReceipt 

func (c *ChainClient) GetTransactionReceipt(ctx context.Context, txHash string) (*types.Receipt, error)

GetTransactionReceipt retrieves the receipt for a transaction

func (*ChainClient) HasAccess 

func (c *ChainClient) HasAccess(ctx context.Context) (bool, error)

HasAccess checks if the wallet has access (owns an NFT from this contract)

type ChallengeRequest 

type ChallengeRequest struct {
	WalletAddress string `json:"wallet_address"`
}

ChallengeRequest is the request body for /api/sdk/auth/challenge

type ChallengeResponse 

type ChallengeResponse struct {
	Challenge string `json:"challenge"`
	ExpiresAt int64  `json:"expires_at"`
}

ChallengeResponse is the response from /api/sdk/auth/challenge

type Command 

type Command struct {
	Trigger      string             `json:"trigger"`
	Argument     string             `json:"argument,omitempty"`
	Description  string             `json:"description,omitempty"`
	Parameters   []CommandParameter `json:"parameters,omitempty"`
	StrictArg    *bool              `json:"strictArg,omitempty"`
	MinArgs      *int               `json:"minArgs,omitempty"`
	MaxArgs      *int               `json:"maxArgs,omitempty"`
	PricePerUnit float64            `json:"pricePerUnit,omitempty"`
	PriceType    string             `json:"priceType,omitempty"`
	TaskUnit     string             `json:"taskUnit,omitempty"`
	TimeUnit     string             `json:"timeUnit,omitempty"`
}

Command represents an agent command

type CommandParameter added in v0.6.4 

type CommandParameter struct {
	Name           string `json:"name"`
	Type           string `json:"type"`
	Required       bool   `json:"required"`
	Description    string `json:"description,omitempty"`
	MinValue       string `json:"minValue,omitempty"`
	IsBillingCount bool   `json:"isBillingCount,omitempty"`
}

CommandParameter represents a parameter for an agent command

type ConfirmMintRequest 

type ConfirmMintRequest struct {
	AgentID         string          `json:"agent_id"`
	AgentName       string          `json:"agent_name"`
	WalletAddress   string          `json:"wallet_address"`
	TokenID         int64           `json:"token_id"`
	TxHash          string          `json:"tx_hash"`
	ConfigHash      string          `json:"config_hash"`
	Description     string          `json:"description,omitempty"`
	Image           string          `json:"image,omitempty"`
	AgentType       string          `json:"agent_type,omitempty"`
	Capabilities    json.RawMessage `json:"capabilities,omitempty"`
	Commands        json.RawMessage `json:"commands,omitempty"`
	NlpFallback     bool            `json:"nlp_fallback"`
	Categories      json.RawMessage `json:"categories,omitempty"`
	MetadataVersion string          `json:"metadata_version,omitempty"`
}

ConfirmMintRequest is the request body for /api/sdk/agent/confirm-mint.

type ConfirmMintResponse 

type ConfirmMintResponse struct {
	Success     bool   `json:"success"`
	ID          string `json:"id"`
	Message     string `json:"message"`
	MetadataURI string `json:"metadata_uri,omitempty"`
}

ConfirmMintResponse is the response from /api/sdk/agent/confirm-mint

type DeployConfig 

type DeployConfig struct {
	// Backend Configuration
	BackendURL  string // Backend URL (default: from BACKEND_URL env or http://localhost:8080)
	RPCEndpoint string // Ethereum RPC endpoint (default: from RPC_ENDPOINT env)

	// Wallet Configuration
	PrivateKey string // Private key (hex, with or without 0x prefix)

	// Agent Configuration
	AgentID         string          // Unique agent identifier (lowercase, hyphens allowed)
	AgentName       string          // Display name for the agent
	Description     string          // Agent description
	Image           string          // Image URL or base64 data
	AgentType       string          // "command", "nlp", or "mcp"
	Capabilities    json.RawMessage // Agent capabilities array
	Commands        json.RawMessage // Agent commands (optional)
	NlpFallback     bool            // Enable NLP fallback
	Categories      json.RawMessage // Agent categories (optional)
	MetadataVersion string          // Metadata version (e.g. "2.3.0")

	// State Management
	StateFilePath string // Path to state file (default: .teneo-deploy-state.json)

	// Advanced Options
	MintPrice *big.Int // Custom mint price (default: 2 PEAQ)
}

DeployConfig contains all configuration for deploying an agent

type DeployRequest 

type DeployRequest struct {
	WalletAddress   string                 `json:"wallet_address"`
	AgentID         string                 `json:"agent_id"`
	AgentName       string                 `json:"agent_name"`
	Description     string                 `json:"description"`
	Image           string                 `json:"image,omitempty"`
	AgentType       string                 `json:"agent_type"`
	Capabilities    json.RawMessage        `json:"capabilities"`
	Commands        json.RawMessage        `json:"commands,omitempty"`
	NlpFallback     bool                   `json:"nlp_fallback"`
	Categories      json.RawMessage        `json:"categories,omitempty"`
	Properties      map[string]interface{} `json:"properties,omitempty"`
	ConfigHash      string                 `json:"config_hash"`
	MetadataVersion string                 `json:"metadata_version,omitempty"`
}

DeployRequest is the request body for /api/sdk/agent/deploy

type DeployResponse 

type DeployResponse struct {
	Signature       string `json:"signature"`
	Nonce           uint64 `json:"nonce"`
	ContractAddress string `json:"contract_address"`
	ChainID         string `json:"chain_id"`
	RPCURL          string `json:"rpc_url"`
	AgentID         string `json:"agent_id"`
	ConfigHash      string `json:"config_hash"`
	// Gasless minting fields (populated when server mints on behalf of SDK)
	TokenID     int64  `json:"token_id,omitempty"`
	TxHash      string `json:"tx_hash,omitempty"`
	MetadataURI string `json:"metadata_uri,omitempty"`
	Gasless     bool   `json:"gasless"`
}

DeployResponse is the response from /api/sdk/agent/deploy

type DeployResult 

type DeployResult struct {
	TokenID         uint64 `json:"token_id"`
	TxHash          string `json:"tx_hash"`
	ContractAddress string `json:"contract_address"`
	MetadataURI     string `json:"metadata_uri"`
	AgentID         string `json:"agent_id"`
	AlreadyMinted   bool   `json:"already_minted"`
}

DeployResult contains the result of a successful deployment

func DeployAgent 

func DeployAgent(cfg DeployConfig) (*DeployResult, error)

DeployAgent is a convenience function for simple deployments

type DeployState 

type DeployState struct {
	AgentID         string       `json:"agent_id"`
	AgentName       string       `json:"agent_name"`
	WalletAddress   string       `json:"wallet_address"`
	TokenID         uint64       `json:"token_id,omitempty"`
	TxHash          string       `json:"tx_hash,omitempty"`
	ContractAddress string       `json:"contract_address,omitempty"`
	RPCURL          string       `json:"rpc_url,omitempty"`
	ConfigHash      string       `json:"config_hash,omitempty"`
	Status          DeployStatus `json:"status"`
	SessionToken    string       `json:"session_token,omitempty"`
	SessionExpiry   int64        `json:"session_expiry,omitempty"`
	Nonce           uint64       `json:"nonce,omitempty"`
	ChainID         string       `json:"chain_id,omitempty"`
	Signature       string       `json:"signature,omitempty"`
	UpdatedAt       time.Time    `json:"updated_at"`
	CreatedAt       time.Time    `json:"created_at"`
	Error           string       `json:"error,omitempty"`
}

DeployState tracks the progress of a deployment operation

func (*DeployState) IsSessionValid 

func (state *DeployState) IsSessionValid() bool

IsSessionValid checks if the stored session token is still valid

type DeployStatus 

type DeployStatus string

DeployStatus represents the current status of a deployment 

const (
	StatusPending   DeployStatus = "pending"   // Metadata uploaded, awaiting mint
	StatusMinted    DeployStatus = "minted"    // NFT minted on-chain, awaiting confirmation
	StatusConfirmed DeployStatus = "confirmed" // Agent saved to database
)

type Deployer 

type Deployer struct {
	// contains filtered or unexported fields
}

Deployer handles the full agent deployment flow

func NewDeployer 

func NewDeployer(config *DeployConfig) (*Deployer, error)

NewDeployer creates a new deployer instance

func (*Deployer) Deploy 

func (d *Deployer) Deploy(ctx context.Context) (*DeployResult, error)

Deploy executes the full deployment flow with resilience and idempotency

type ErrorResponse 

type ErrorResponse struct {
	Success bool   `json:"success"`
	Error   string `json:"error"`
}

ErrorResponse represents an error response from the API

type HTTPClient 

type HTTPClient struct {
	// contains filtered or unexported fields
}

HTTPClient wraps HTTP operations for SDK deploy endpoints

func NewHTTPClient 

func NewHTTPClient(baseURL string) *HTTPClient

NewHTTPClient creates a new HTTP client for SDK endpoints

func (*HTTPClient) Abandon 

func (c *HTTPClient) Abandon(req *AbandonRequest) (*AbandonResponse, error)

Abandon calls the abandon endpoint to delete an unminted reservation

func (*HTTPClient) ConfirmMint 

func (c *HTTPClient) ConfirmMint(sessionToken string, req *ConfirmMintRequest) (*ConfirmMintResponse, error)

ConfirmMint confirms the mint and saves the agent to the database

func (*HTTPClient) Deploy 

func (c *HTTPClient) Deploy(sessionToken string, req *DeployRequest) (*DeployResponse, error)

Deploy calls the deploy endpoint to prepare for minting

func (*HTTPClient) GetChallenge 

func (c *HTTPClient) GetChallenge(walletAddress string) (string, error)

GetChallenge requests a challenge for authentication (used by sync flow)

func (*HTTPClient) GetSchema 

func (c *HTTPClient) GetSchema() (*SchemaResponse, error)

GetSchema fetches the validation schema from the backend

func (*HTTPClient) RequestChallenge 

func (c *HTTPClient) RequestChallenge(walletAddress string) (*ChallengeResponse, error)

RequestChallenge requests an authentication challenge from the backend

func (*HTTPClient) Sync 

func (c *HTTPClient) Sync(req *SyncRequest) (*SyncResponse, error)

Sync calls the sync endpoint to check agent status

func (*HTTPClient) UpdateMetadata 

func (c *HTTPClient) UpdateMetadata(sessionToken string, req *UpdateMetadataRequest) (*UpdateMetadataResponse, error)

UpdateMetadata calls the update endpoint to re-upload metadata and update on-chain tokenURI

func (*HTTPClient) VerifySignature 

func (c *HTTPClient) VerifySignature(walletAddress, challenge, signature string) (*VerifyResponse, error)

VerifySignature verifies the signed challenge and returns a session token

type MintConfig 

type MintConfig struct {
	PrivateKey  string // Wallet private key (hex)
	BackendURL  string // Backend API URL
	RPCEndpoint string // Blockchain RPC endpoint
}

MintConfig contains configuration for minting

type MintResult 

type MintResult struct {
	TokenID         uint64 `json:"token_id"`
	TxHash          string `json:"tx_hash,omitempty"`
	AgentID         string `json:"agent_id,omitempty"`
	Status          string `json:"status,omitempty"` // "MINTED", "ALREADY_OWNED", "UPDATE_REQUIRED"
	ContractAddress string `json:"contract_address,omitempty"`
	Message         string `json:"message,omitempty"`
}

MintResult contains the result of a mint operation

func MintAgent 

func MintAgent(jsonPath string, config *MintConfig) (*MintResult, error)

Mint is a convenience function for simple minting

type Minter 

type Minter struct {
	// contains filtered or unexported fields
}

Minter handles the gasless minting flow

func NewMinter 

func NewMinter(config *MintConfig) (*Minter, error)

NewMinter creates a new minter instance

func (*Minter) Abandon 

func (m *Minter) Abandon(agentID string) error

Abandon abandons an unminted agent reservation

func (*Minter) Mint 

func (m *Minter) Mint(jsonPath string) (*MintResult, error)

Mint loads an agent config from JSON file and mints/syncs the agent

func (*Minter) MintWithContext 

func (m *Minter) MintWithContext(ctx context.Context, jsonPath string) (*MintResult, error)

MintWithContext loads an agent config from JSON file and mints/syncs with context

type SchemaCache 

type SchemaCache struct {
	Schema    *SchemaResponse
	FetchedAt time.Time
}

SchemaCache caches the schema response

type SchemaResponse 

type SchemaResponse struct {
	Schema        json.RawMessage `json:"schema"`
	SchemaVersion string          `json:"schema_version"`
	Signature     string          `json:"signature"`
	MaxJSONSize   int             `json:"max_json_size"` // Max allowed JSON size in bytes
}

SchemaResponse is the response from GET /api/sdk/schema

type StateManager 

type StateManager struct {
	// contains filtered or unexported fields
}

StateManager handles persistent state storage for deploy operations

func NewStateManager 

func NewStateManager(filePath string) *StateManager

NewStateManager creates a new state manager with the specified file path

func (*StateManager) CreateInitialState 

func (sm *StateManager) CreateInitialState(agentID, agentName, walletAddress string) (*DeployState, error)

CreateInitialState creates a new state for a fresh deployment

func (*StateManager) Delete 

func (sm *StateManager) Delete() error

Delete removes the state file

func (*StateManager) GetFilePath 

func (sm *StateManager) GetFilePath() string

GetFilePath returns the path to the state file

func (*StateManager) Load 

func (sm *StateManager) Load() (*DeployState, error)

Load reads the state from disk

func (*StateManager) Save 

func (sm *StateManager) Save(state *DeployState) error

Save writes the state to disk atomically

func (*StateManager) SetConfirmed 

func (sm *StateManager) SetConfirmed() error

SetConfirmed updates state after successful database confirmation

func (*StateManager) SetMinted 

func (sm *StateManager) SetMinted(tokenID uint64, txHash string) error

SetMinted updates state after successful on-chain mint

func (*StateManager) UpdateStatus 

func (sm *StateManager) UpdateStatus(status DeployStatus) error

UpdateStatus atomically updates the status and saves

type SyncRequest 

type SyncRequest struct {
	Wallet        string `json:"wallet"`
	AgentID       string `json:"agent_id"`
	ConfigHash    string `json:"config_hash"`
	Challenge     string `json:"challenge"`
	Signature     string `json:"signature"`
	SchemaVersion string `json:"schema_version,omitempty"`
}

SyncRequest is the request body for POST /api/sdk/agent/sync

type SyncResponse 

type SyncResponse struct {
	Status             string `json:"status"` // SYNCED, MINT_REQUIRED, RESUME_MINT, UPDATE_REQUIRED, AUTO_CONFIRMED
	TokenID            *int64 `json:"token_id,omitempty"`
	ContractAddress    string `json:"contract_address,omitempty"`
	AgentID            string `json:"agent_id,omitempty"`
	Creator            string `json:"creator,omitempty"`
	CurrentHash        string `json:"current_hash,omitempty"`
	NewHash            string `json:"new_hash,omitempty"`
	Message            string `json:"message,omitempty"`
	HasPendingMetadata bool   `json:"has_pending_metadata,omitempty"`
	RPCURL             string `json:"rpc_url,omitempty"`
	ConfigHash         string `json:"config_hash,omitempty"`
}

SyncResponse is the response from POST /api/sdk/agent/sync

type UpdateMetadataRequest 

type UpdateMetadataRequest struct {
	WalletAddress   string          `json:"wallet_address"`
	AgentID         string          `json:"agent_id"`
	AgentName       string          `json:"agent_name"`
	Description     string          `json:"description"`
	Image           string          `json:"image,omitempty"`
	AgentType       string          `json:"agent_type"`
	Capabilities    json.RawMessage `json:"capabilities"`
	Commands        json.RawMessage `json:"commands,omitempty"`
	NlpFallback     bool            `json:"nlp_fallback"`
	Categories      json.RawMessage `json:"categories,omitempty"`
	ConfigHash      string          `json:"config_hash"`
	MetadataVersion string          `json:"metadata_version,omitempty"`
}

UpdateMetadataRequest is the request body for POST /api/sdk/agent/update

type UpdateMetadataResponse 

type UpdateMetadataResponse struct {
	Success     bool   `json:"success"`
	IpfsHash    string `json:"ipfs_hash,omitempty"`
	MetadataURI string `json:"metadata_uri,omitempty"`
	TxHash      string `json:"tx_hash,omitempty"`
	Message     string `json:"message"`
}

UpdateMetadataResponse is the response from POST /api/sdk/agent/update

type VerifyRequest 

type VerifyRequest struct {
	WalletAddress string `json:"wallet_address"`
	Challenge     string `json:"challenge"`
	Signature     string `json:"signature"`
}

VerifyRequest is the request body for /api/sdk/auth/verify

type VerifyResponse 

type VerifyResponse struct {
	SessionToken string `json:"session_token"`
	ExpiresAt    int64  `json:"expires_at"`
}

VerifyResponse is the response from /api/sdk/auth/verify

type WALClient 

type WALClient struct {
	// contains filtered or unexported fields
}

WALClient handles Write-Ahead Log operations

func NewWALClient 

func NewWALClient() *WALClient

NewWALClient creates a new WAL client

func NewWALClientWithDir 

func NewWALClientWithDir(walDir string) *WALClient

NewWALClientWithDir creates a WAL client with custom directory

func (*WALClient) CleanupOld 

func (w *WALClient) CleanupOld(maxAge time.Duration) (int, error)

CleanupOld removes WAL entries older than the specified duration

func (*WALClient) Delete 

func (w *WALClient) Delete(agentID string) error

Delete removes a WAL entry

func (*WALClient) Exists 

func (w *WALClient) Exists(agentID string) bool

Exists checks if a WAL entry exists

func (*WALClient) List 

func (w *WALClient) List() ([]*WALEntry, error)

List lists all WAL entries

func (*WALClient) Load 

func (w *WALClient) Load(agentID string) (*WALEntry, error)

Load loads a WAL entry for an agent

func (*WALClient) Save 

func (w *WALClient) Save(entry *WALEntry) error

Save saves a WAL entry

type WALEntry 

type WALEntry struct {
	AgentID         string    `json:"agent_id"`
	Wallet          string    `json:"wallet"`
	State           string    `json:"state"` // IDLE, MINTING, CONFIRMING
	PendingTxHash   string    `json:"pending_tx_hash,omitempty"`
	PendingTokenID  *uint64   `json:"pending_token_id,omitempty"`
	ContractAddress string    `json:"contract_address,omitempty"`
	ChainID         string    `json:"chain_id,omitempty"`
	RPCURL          string    `json:"rpc_url,omitempty"`
	Signature       string    `json:"signature,omitempty"`
	ConfigHash      string    `json:"config_hash,omitempty"`
	CreatedAt       time.Time `json:"created_at"`
	UpdatedAt       time.Time `json:"updated_at"`
}

WALEntry represents a Write-Ahead Log entry for crash recovery

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.