api,client,www: add roots endpoint, deprecate root endpoint (#78)

Author: worm-emoji

api/api.go

@@ -34,6 +34,7 @@ func (s *Server) Handler(env, gitSha string) http.Handler {
 	mux.HandleFunc("/api/v1/tree", s.TreeHandler)
 	mux.HandleFunc("/api/v1/proof", s.GetProof)
 	mux.HandleFunc("/api/v1/root", s.GetRoot)
+	mux.HandleFunc("/api/v1/roots", s.GetRoot)
 	mux.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
 		fmt.Fprint(w, gitSha)
 	})

api/root.go

@@ -2,7 +2,6 @@ package api
 
 import (
 	"encoding/json"
-	"errors"
 	"net/http"
 	"strings"
 
@@ -30,6 +29,11 @@ func proofURLToDBQuery(param string) string {
 func (s *Server) GetRoot(w http.ResponseWriter, r *http.Request) {
 	type rootResp struct {
 		Root hexutil.Bytes `json:"root"`
+		Note string        `json:"note"`
+	}
+
+	type rootsResp struct {
+		Roots []hexutil.Bytes `json:"roots"`
 	}
 
 	var (
@@ -45,30 +49,34 @@ func (s *Server) GetRoot(w http.ResponseWriter, r *http.Request) {
 	const q = `
 		SELECT root
 		FROM trees
-		WHERE proofs_array(proofs) <@ proofs_array($1);
+		WHERE proofs_array(proofs) @> proofs_array($1);
 	`
-	rr := rootResp{}
+	roots := make([]hexutil.Bytes, 0)
+	rb := make(hexutil.Bytes, 0)
 
-	// should only return one row, using QueryFunc to verify
-	// that's the case and return an error if not (we've had
-	// issues with this in the past)
-	hasRow := false
-	_, err := s.db.QueryFunc(ctx, q, []interface{}{dbQuery}, []interface{}{&rr.Root}, func(qfr pgx.QueryFuncRow) error {
-		if hasRow {
-			return errors.New("multiple rows returned")
-		}
-		hasRow = true
+	_, err := s.db.QueryFunc(ctx, q, []interface{}{dbQuery}, []interface{}{&rb}, func(qfr pgx.QueryFuncRow) error {
+		roots = append(roots, rb)
 		return nil
 	})
 
 	if err != nil {
 		s.sendJSONError(r, w, err, http.StatusInternalServerError, "selecting root")
 		return
-	} else if len(rr.Root) == 0 { // db.QueryFunc doesn't return pgx.ErrNoRows
+	} else if len(roots) == 0 { // db.QueryFunc doesn't return pgx.ErrNoRows
 		s.sendJSONError(r, w, nil, http.StatusNotFound, "root not found for proofs")
 		return
 	}
 
 	w.Header().Set("Cache-Control", "public, max-age=3600")
-	s.sendJSON(r, w, rr)
+
+	if strings.HasPrefix(r.URL.Path, "/api/v1/roots") {
+		s.sendJSON(r, w, rootsResp{Roots: roots})
+	} else {
+		// The original functionality of this endpoint, getting one root for
+		// a given proof, is deprecated. This is because for smaller trees,
+		// there are often collisions with the same root for different proofs.
+		// This bit of code is for backwards compatibility.
+		const note = `This endpoint is deprecated. For smaller trees, there are often collisions with the same root for different proofs. Please use the /v1/api/roots endpoint instead.`
+		s.sendJSON(r, w, rootResp{Root: roots[0], Note: note})
+	}
 }

clients/go/lanyard/client.go

@@ -260,20 +260,22 @@ func (c *Client) GetProofFromAddr(
 	return resp, nil
 }
 
-type RootResponse struct {
-	Root hexutil.Bytes `json:"root"`
+type RootsResponse struct {
+	Roots []hexutil.Bytes `json:"roots"`
 }
 
 // If a Merkle tree has been published to Lanyard,
-// GetRootFromLeaf will return the root of the tree
+// GetRootsFromProof will return the root of the tree
 // based on a proof of a leaf. This endpoint will return
 // ErrNotFound if the tree associated with the
-// leaf has not been published.
-func (c *Client) GetRootFromProof(
+// leaf has not been published. This API response is deprecated
+// as there may be more than one root per proof. Use GetRootsFromProof
+// instead.
+func (c *Client) GetRootsFromProof(
 	ctx context.Context,
 	proof []hexutil.Bytes,
-) (*RootResponse, error) {
-	resp := &RootResponse{}
+) (*RootsResponse, error) {
+	resp := &RootsResponse{}
 
 	if len(proof) == 0 {
 		return nil, xerrors.New("proof must not be empty")
@@ -286,7 +288,7 @@ func (c *Client) GetRootFromProof(
 
 	err := c.sendRequest(
 		ctx, http.MethodGet,
-		fmt.Sprintf("/root?proof=%s",
+		fmt.Sprintf("/roots?proof=%s",
 			strings.Join(pq, ","),
 		),
 		nil, resp,

clients/go/lanyard/client_integration_test.go

@@ -86,21 +86,21 @@ func TestGetProofFromAddr(t *testing.T) {
 	}
 }
 
-func TestGetRootFromProof(t *testing.T) {
+func TestGetRootsFromProof(t *testing.T) {
 	p, err := client.GetProofFromLeaf(context.Background(), hexutil.MustDecode(basicRoot), basicMerkle[0])
 
 	if err != nil {
 		t.Fatal(err)
 	}
 
-	root, err := client.GetRootFromProof(context.Background(), p.Proof)
+	resp, err := client.GetRootsFromProof(context.Background(), p.Proof)
 
 	if err != nil {
 		t.Fatal(err)
 	}
 
-	if root.Root.String() != basicRoot {
-		t.Fatalf("expected %s, got %s", basicRoot, root.Root.String())
+	if resp.Roots[0].String() != basicRoot {
+		t.Fatalf("expected %s, got %s", basicRoot, resp.Roots[0].String())
 	}
 
 }

example/src/api.ts

@@ -80,10 +80,12 @@ const getProofForIndexedAddress = async (
   return await proofRes.json()
 }
 
-const getRootFromProof = async (proof: string[]): Promise<string> => {
-  const rootRes = await fetch(`${baseUrl}/api/v1/root?proof=${proof.join(',')}`)
-  const resp: { root: string } = await rootRes.json()
-  return resp.root
+const getRootsFromProof = async (proof: string[]): Promise<string> => {
+  const rootRes = await fetch(
+    `${baseUrl}/api/v1/roots?proof=${proof.join(',')}`,
+  )
+  const resp: { roots: string[] } = await rootRes.json()
+  return resp.roots
 }
 
 const encode = utils.defaultAbiCoder.encode.bind(utils.defaultAbiCoder)
@@ -230,6 +232,6 @@ checkProofEquality(
   ),
 )
 
-const root = await getRootFromProof(encodedPackedProof)
-console.log('root from proof', root)
-checkRootEquality(root, encodedPackedMerkleRoot)
+const root = await getRootsFromProof(encodedPackedProof)
+console.log('roots from proof', root[0])
+checkRootEquality(root[0], encodedPackedMerkleRoot)

www/components/Docs/codeSnippets.ts

@@ -50,12 +50,12 @@ GET https://lanyard.org/api/v1/proof?root={root}&unhashedLeaf={unhashedLeaf}
 }
 `.trim()
 
-export const rootCode = `
+export const rootsCode = `
 // proof is 0x prefixed, comma separated values
-GET https://lanyard.org/api/v1/root?proof={proof}
+GET https://lanyard.org/api/v1/roots?proof={proof}
 
 // Response body
 {
-  "root": "0x0000000000000000000000000000000000000003" // returns error if not found
+  "roots": ["0x0000000000000000000000000000000000000003"] // returns error if not found
 }
 `.trim()

www/components/Docs/index.tsx

@@ -2,7 +2,7 @@ import Link from 'next/link'
 import { brandUnderlineClasses } from 'utils/theme'
 import PageTitle from 'components/PageTitle'
 import CodeBlock from 'components/CodeBlock'
-import { createCode, lookupCode, proofCode, rootCode } from './codeSnippets'
+import { createCode, lookupCode, proofCode, rootsCode } from './codeSnippets'
 import Section from './Section'
 
 export default function Docs() {
@@ -43,10 +43,10 @@ export default function Docs() {
           <CodeBlock code={proofCode} language="javascript" />
         </Section>
         <Section
-          title="Looking up a root for a given proof"
+          title="Looking up potential roots for a given proof"
           description="A more advanced use but helpful if you just have a proof."
         >
-          <CodeBlock code={rootCode} language="javascript" />
+          <CodeBlock code={rootsCode} language="javascript" />
         </Section>
       </div>
     </div>