feat(antd-go)!: adopt PaymentMode enum + put/get convention (1/11)

README.md

@@ -276,7 +276,7 @@ func main() {
     if err != nil { log.Fatal(err) }
     fmt.Printf("Network: %s\n", health.Network)
 
-    result, err := client.DataPutPublic(ctx, []byte("Hello, Autonomi!"))
+    result, err := client.DataPutPublic(ctx, []byte("Hello, Autonomi!"), antd.PaymentModeAuto)
     if err != nil { log.Fatal(err) }
     fmt.Printf("Address: %s\n", result.Address)
 

antd-go/README.md

@@ -34,11 +34,11 @@ func main() {
         health.OK, health.Network, health.Version, health.EvmNetwork)
 
     // Store data
-    result, err := client.DataPutPublic(ctx, []byte("Hello, Autonomi!"))
+    result, err := client.DataPutPublic(ctx, []byte("Hello, Autonomi!"), antd.PaymentModeAuto)
     if err != nil {
         log.Fatal(err)
     }
-    fmt.Printf("Stored at %s (cost: %s atto)\n", result.Address, result.Cost)
+    fmt.Printf("Stored at %s (chunks: %d, mode: %s)\n", result.Address, result.ChunksStored, result.PaymentModeUsed)
 
     // Retrieve data
     data, err := client.DataGetPublic(ctx, result.Address)
@@ -75,13 +75,23 @@ client := antd.NewClient(antd.DefaultBaseURL, antd.WithTimeout(30 * time.Second)
 // Custom HTTP client
 client := antd.NewClient(antd.DefaultBaseURL, antd.WithHTTPClient(myHTTPClient))
 
-// Payment mode for uploads (defaults to "auto")
-result, _ := client.DataPutPublic(ctx, data, antd.WithPaymentMode("merkle"))
-// "auto" = merkle for 64+ chunks, single otherwise
-// "merkle" = force batch payments (saves gas, min 2 chunks)
-// "single" = per-chunk payments
+// Payment mode is a typed enum passed positionally to put/cost methods.
+result, _ := client.DataPutPublic(ctx, data, antd.PaymentModeMerkle)
+// antd.PaymentModeAuto   — server picks merkle for 64+ chunks, single otherwise
+// antd.PaymentModeMerkle — force batch payments (saves gas, min 2 chunks)
+// antd.PaymentModeSingle — per-chunk payments
 ```
 
+### Put/Get naming convention
+
+Methods follow a "private by default" convention: the unqualified verb is the
+private variant; the `_public` suffix marks the public variant.
+
+- `DataPut` / `DataGet` — private. Returns/consumes a caller-held DataMap.
+- `DataPutPublic` / `DataGetPublic` — public. Stores/fetches the DataMap on-network.
+- `FilePut` / `FileGet` — private file upload/download.
+- `FilePutPublic` / `FileGetPublic` — public file upload/download.
+
 ## API Reference
 
 All methods take a `context.Context` as the first parameter for cancellation and timeout control.
@@ -94,11 +104,11 @@ All methods take a `context.Context` as the first parameter for cancellation and
 ### Data (Immutable)
 | Method | Description |
 |--------|-------------|
-| `DataPutPublic(ctx, data)` | Store public data |
-| `DataGetPublic(ctx, address)` | Retrieve public data |
-| `DataPutPrivate(ctx, data)` | Store encrypted private data |
-| `DataGetPrivate(ctx, dataMap)` | Retrieve private data |
-| `DataCost(ctx, data)` | Estimate storage cost — returns `*UploadCostEstimate` with size, chunks, gas, payment mode |
+| `DataPut(ctx, data, paymentMode)` | Store encrypted private data; returns the caller-held DataMap |
+| `DataGet(ctx, dataMap)` | Retrieve private data from a caller-held DataMap |
+| `DataPutPublic(ctx, data, paymentMode)` | Store public data; returns the on-network DataMap address |
+| `DataGetPublic(ctx, address)` | Retrieve public data by address |
+| `DataCost(ctx, data, paymentMode)` | Estimate storage cost — returns `*UploadCostEstimate` |
 
 ### Chunks
 | Method | Description |
@@ -109,9 +119,11 @@ All methods take a `context.Context` as the first parameter for cancellation and
 ### Files
 | Method | Description |
 |--------|-------------|
-| `FileUploadPublic(ctx, path)` | Upload a file |
-| `FileDownloadPublic(ctx, address, destPath)` | Download a file |
-| `FileCost(ctx, path, isPublic)` | Estimate upload cost — returns `*UploadCostEstimate` with size, chunks, gas, payment mode |
+| `FilePut(ctx, path, paymentMode)` | Upload a file privately; returns the caller-held DataMap |
+| `FileGet(ctx, dataMap, destPath)` | Download a private file from a caller-held DataMap |
+| `FilePutPublic(ctx, path, paymentMode)` | Upload a file publicly; returns the on-network DataMap address |
+| `FileGetPublic(ctx, address, destPath)` | Download a public file by address |
+| `FileCost(ctx, path, isPublic, paymentMode)` | Estimate upload cost — returns `*UploadCostEstimate` |
 
 ## gRPC Transport
 

antd-go/client.go

@@ -8,7 +8,6 @@ import (
 	"fmt"
 	"io"
 	"net/http"
-	"net/url"
 	"strings"
 	"time"
 )
@@ -199,48 +198,56 @@ const (
 
 // --- Data ---
 
-// DataPutPublic stores public immutable data on the network.
-func (c *Client) DataPutPublic(ctx context.Context, data []byte, paymentMode ...PaymentMode) (*PutResult, error) {
-	body := map[string]any{
-		"data": b64Encode(data),
-	}
-	if len(paymentMode) > 0 && paymentMode[0] != "" {
-		body["payment_mode"] = string(paymentMode[0])
-	}
-	j, _, err := c.doJSON(ctx, http.MethodPost, "/v1/data/public", body)
+// DataPut stores private encrypted data on the network and returns the
+// caller-held DataMap (hex). The DataMap is NOT stored on-network — the caller
+// keeps it as the only retrieval handle.
+func (c *Client) DataPut(ctx context.Context, data []byte, paymentMode PaymentMode) (*DataPutResult, error) {
+	j, _, err := c.doJSON(ctx, http.MethodPost, "/v1/data", map[string]any{
+		"data":         b64Encode(data),
+		"payment_mode": string(paymentMode),
+	})
 	if err != nil {
 		return nil, err
 	}
-	return &PutResult{Cost: str(j, "cost"), Address: str(j, "address")}, nil
+	return &DataPutResult{
+		DataMap:         str(j, "data_map"),
+		ChunksStored:    unum64(j, "chunks_stored"),
+		PaymentModeUsed: str(j, "payment_mode_used"),
+	}, nil
 }
 
-// DataGetPublic retrieves public data by address.
-func (c *Client) DataGetPublic(ctx context.Context, address string) ([]byte, error) {
-	j, _, err := c.doJSON(ctx, http.MethodGet, "/v1/data/public/"+address, nil)
+// DataGet retrieves private data from a caller-held DataMap (hex).
+func (c *Client) DataGet(ctx context.Context, dataMap string) ([]byte, error) {
+	j, _, err := c.doJSON(ctx, http.MethodPost, "/v1/data/get", map[string]any{
+		"data_map": dataMap,
+	})
 	if err != nil {
 		return nil, err
 	}
 	return b64Decode(str(j, "data"))
 }
 
-// DataPutPrivate stores private encrypted data on the network.
-func (c *Client) DataPutPrivate(ctx context.Context, data []byte, paymentMode ...PaymentMode) (*PutResult, error) {
-	body := map[string]any{
-		"data": b64Encode(data),
-	}
-	if len(paymentMode) > 0 && paymentMode[0] != "" {
-		body["payment_mode"] = string(paymentMode[0])
-	}
-	j, _, err := c.doJSON(ctx, http.MethodPost, "/v1/data/private", body)
+// DataPutPublic stores public immutable data on the network. The DataMap is
+// stored on-network as an extra chunk; the returned address is the shareable
+// retrieval handle.
+func (c *Client) DataPutPublic(ctx context.Context, data []byte, paymentMode PaymentMode) (*DataPutPublicResult, error) {
+	j, _, err := c.doJSON(ctx, http.MethodPost, "/v1/data/public", map[string]any{
+		"data":         b64Encode(data),
+		"payment_mode": string(paymentMode),
+	})
 	if err != nil {
 		return nil, err
 	}
-	return &PutResult{Cost: str(j, "cost"), Address: str(j, "data_map")}, nil
+	return &DataPutPublicResult{
+		Address:         str(j, "address"),
+		ChunksStored:    unum64(j, "chunks_stored"),
+		PaymentModeUsed: str(j, "payment_mode_used"),
+	}, nil
 }
 
-// DataGetPrivate retrieves private data using a data map.
-func (c *Client) DataGetPrivate(ctx context.Context, dataMap string) ([]byte, error) {
-	j, _, err := c.doJSON(ctx, http.MethodGet, "/v1/data/private?data_map="+url.QueryEscape(dataMap), nil)
+// DataGetPublic retrieves public data by address.
+func (c *Client) DataGetPublic(ctx context.Context, address string) ([]byte, error) {
+	j, _, err := c.doJSON(ctx, http.MethodGet, "/v1/data/public/"+address, nil)
 	if err != nil {
 		return nil, err
 	}
@@ -251,9 +258,10 @@ func (c *Client) DataGetPrivate(ctx context.Context, dataMap string) ([]byte, er
 //
 // The server samples a small number of chunk addresses and extrapolates —
 // much faster than quoting every chunk on slow networks. Gas is advisory.
-func (c *Client) DataCost(ctx context.Context, data []byte) (*UploadCostEstimate, error) {
+func (c *Client) DataCost(ctx context.Context, data []byte, paymentMode PaymentMode) (*UploadCostEstimate, error) {
 	j, _, err := c.doJSON(ctx, http.MethodPost, "/v1/data/cost", map[string]any{
-		"data": b64Encode(data),
+		"data":         b64Encode(data),
+		"payment_mode": string(paymentMode),
 	})
 	if err != nil {
 		return nil, err
@@ -360,19 +368,45 @@ func (c *Client) FinalizeChunkUpload(ctx context.Context, uploadID string, txHas
 
 // --- Files ---
 
-// FileUploadPublic uploads a local file to the network.
-func (c *Client) FileUploadPublic(ctx context.Context, path string, paymentMode ...PaymentMode) (*FileUploadResult, error) {
-	body := map[string]any{
-		"path": path,
-	}
-	if len(paymentMode) > 0 && paymentMode[0] != "" {
-		body["payment_mode"] = string(paymentMode[0])
+// FilePut uploads a local file as a private upload and returns the caller-held
+// DataMap (hex). The DataMap is NOT stored on-network.
+func (c *Client) FilePut(ctx context.Context, path string, paymentMode PaymentMode) (*FilePutResult, error) {
+	j, _, err := c.doJSON(ctx, http.MethodPost, "/v1/files", map[string]any{
+		"path":         path,
+		"payment_mode": string(paymentMode),
+	})
+	if err != nil {
+		return nil, err
 	}
-	j, _, err := c.doJSON(ctx, http.MethodPost, "/v1/files/upload/public", body)
+	return &FilePutResult{
+		DataMap:         str(j, "data_map"),
+		StorageCostAtto: str(j, "storage_cost_atto"),
+		GasCostWei:      str(j, "gas_cost_wei"),
+		ChunksStored:    unum64(j, "chunks_stored"),
+		PaymentModeUsed: str(j, "payment_mode_used"),
+	}, nil
+}
+
+// FileGet downloads a private file from a caller-held DataMap (hex) into destPath.
+func (c *Client) FileGet(ctx context.Context, dataMap, destPath string) error {
+	_, _, err := c.doJSON(ctx, http.MethodPost, "/v1/files/get", map[string]any{
+		"data_map":  dataMap,
+		"dest_path": destPath,
+	})
+	return err
+}
+
+// FilePutPublic uploads a local file as a public upload. The DataMap is stored
+// on-network as an extra chunk; the returned address is the shareable handle.
+func (c *Client) FilePutPublic(ctx context.Context, path string, paymentMode PaymentMode) (*FilePutPublicResult, error) {
+	j, _, err := c.doJSON(ctx, http.MethodPost, "/v1/files/public", map[string]any{
+		"path":         path,
+		"payment_mode": string(paymentMode),
+	})
 	if err != nil {
 		return nil, err
 	}
-	return &FileUploadResult{
+	return &FilePutPublicResult{
 		Address:         str(j, "address"),
 		StorageCostAtto: str(j, "storage_cost_atto"),
 		GasCostWei:      str(j, "gas_cost_wei"),
@@ -381,9 +415,9 @@ func (c *Client) FileUploadPublic(ctx context.Context, path string, paymentMode
 	}, nil
 }
 
-// FileDownloadPublic downloads a file from the network to a local path.
-func (c *Client) FileDownloadPublic(ctx context.Context, address, destPath string) error {
-	_, _, err := c.doJSON(ctx, http.MethodPost, "/v1/files/download/public", map[string]any{
+// FileGetPublic downloads a public file from an on-network DataMap address into destPath.
+func (c *Client) FileGetPublic(ctx context.Context, address, destPath string) error {
+	_, _, err := c.doJSON(ctx, http.MethodPost, "/v1/files/public/get", map[string]any{
 		"address":   address,
 		"dest_path": destPath,
 	})
@@ -394,10 +428,11 @@ func (c *Client) FileDownloadPublic(ctx context.Context, address, destPath strin
 //
 // The server samples a small number of chunk addresses and extrapolates —
 // much faster than quoting every chunk on slow networks. Gas is advisory.
-func (c *Client) FileCost(ctx context.Context, path string, isPublic bool) (*UploadCostEstimate, error) {
+func (c *Client) FileCost(ctx context.Context, path string, isPublic bool, paymentMode PaymentMode) (*UploadCostEstimate, error) {
 	j, _, err := c.doJSON(ctx, http.MethodPost, "/v1/files/cost", map[string]any{
-		"path":      path,
-		"is_public": isPublic,
+		"path":         path,
+		"is_public":    isPublic,
+		"payment_mode": string(paymentMode),
 	})
 	if err != nil {
 		return nil, err